Generate API Portal using Docs as Code

The API Portal generated via APIMatic docs as code process allows the entire API documentation to be managed as code via a Git repository and contains:

1. Comprehensive API reference documentation
2. Language-specific API documentation
3. Language-idiomatic SDKs with code samples
4. Custom Markdown guides

note

• An authentication key is required to authenticate APIMatic APIs. To obtain this key, please follow the steps mentioned in this section.
• For free access to the Docs as Code API, drop an email at support@apimatic.io.
• Take a look at this GitHub repository for a sample docs as code workflow.

1. Download the GitHub repository in a zip file using the Download ZIP option. This will be used to generate the complete API portal containing the latest API documentation and SDKs for your API definition.

   

The GitHub repository contains the following folders with the given structure:

Spec Directory

The spec directory contains:

• OpenAPI specification file

Some considerations for API specification files in this directory are:

• The API specification must be in one of the formats supported by APIMatic.
• The API specification format is detected automatically by APIMatic.
• You can include multiple API Specification files here if you want them all documented in the same API Portal and APIMatic will merge them for you, even if they are in different specification formats.

For further details, take a look at this sample spec directory. If you have multiple API specifications, go to the API specification documentation for additional handling.

Content Directory

The content directory contains:

• Custom Markdown guides written in GitHub-flavored Markdown for your product documentation, changelogs, step-by-step tutorial guides, etc.
• Custom table-of-content as the content\toc.yml file. This allows you to create a content hierarchy displayed in the navigation sidebar.

A sample toc.yml file looks like:

toc:
  - group: Getting Started
    items:
      - generate: How to Get Started
        from: getting-started
  - group: Guides
    dir: guides
  - generate: API Endpoints
    from: endpoints
  - generate: Models
    from: models

Providing custom content is optional. For further details, go to the Custom Content Documentation.

Static Directory

The static directory contains:

• Images
• Logos
• PDFs

Providing static content is optional. Take a look at this sample static directory.

Build Configuration File

The name of the build configuration file ends with APIMATIC-BUILD.json and should be placed in the root directory. You can customize the generated API Portal by specifying properties in the build file such as:

• Which SDKs to generate and include within the portal.
• Package information for the SDKs to be included in the documentation.
• Page title and logo image for the portal.
• Portal color theme and typography.
• Custom CSS.

A minimal build file would look like this:

{
  "$schema": "https://titan.apimatic.io/api/build/schema",
  "buildFileVersion": "1",
  "generatePortal": {
     "apiSpecs": [
      "spec1",
      "spec2"
    ],
    "languageConfig": {
      "http": {}
    }
  }
}

To create a build file, take a look at APIMatic Build File documentation.

2. Use APIMatic API and invoke the Generate On-Prem Portal via Build Input Endpoint by providing the zip file downloaded in step 1. The API response contains a static API Portal.

   

3. Host the static API Portal generated through the endpoint on any web server. Preview the generated Portal using http-server or similar tools.

   

To automate the entire docs as code process, go to the Automate API Portal using Docs as Code.