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:
- Comprehensive API reference documentation
- Language-specific API documentation
- Language-idiomatic SDKs with code samples
- Custom Markdown guides
- For free access to the Docs as Code API, drop an email at
- Take a look at this GitHub repository for a sample docs as code workflow.
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:
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.
The content directory contains:
- Custom Markdown guides written in GitHub-flavoured 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:
- group: Getting Started
- generate: How to Get Started
- group: Guides
- generate: API Endpoints
- generate: Models
Providing custom content is optional. For further details, go to the Custom Content Documentation.
The static directory contains:
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:
To create a build file, take a look at APIMatic Build File documentation.
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.
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.