Skip to main content

Contents of the Build Directory

Your API Portal is managed through a build directory that contains all the files and folders required to configure and customize the portal. Understanding this structure is essential. To get started with creating the build directory, follow the APIMatic CLI's Quickstart Guide.

A typical build directory looks like this:

  ├─ APIMATIC-BUILD.json # Defines all configurations for the API portal
  ├─ README.md
  ├─ content # Includes custom documentation pages in Markdown
  |  ├─ guides
  |  |  └─ guide1.md
  |  └─ toc.yml # Controls the navigation structure
  ├─ spec # Contains API definition files
  |  ├─ APIMATIC-META.json
  |  └─ openapi.json
  └─ static # Includes all static files, such as images, GIFs, and PDFs
    └─ images
        ├─ favicon.ico
        └─ logo.png

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're 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
  - generate: SDK Infrastructure
    from: sdk-infra

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": {}
    }
  }
}