How-to guidesPublish API documentation

Publish API documentation

Documentation written by hand falls behind the API it describes. Built from the contract, it changes when the API does. This guide builds a documentation site from an OpenAPI document and an AsyncAPI one, adds translations and changelogs, publishes it, and shows how to put a reference into an existing page instead. Swagger 2.0, GraphQL and Protobuf files work the same way.

You need the CLI and Node.js installed; the Quickstart shows how.

Build a site

Use your own files, or download the Carpet Express OpenAPI definition as openapi.yaml and AsyncAPI definition as events.asyncapi.yaml. These describe a fictional service; their sample endpoints aren’t live.

apigenie-generator docs openapi.yaml events.asyncapi.yaml -o docs
cd docs
npm install
npm run build

The first command writes a docs bundle into docs/: the resolved documents and a manifest, with an npm project that depends on the doc components. The build renders it into docs/dist/: a page per API, operation and schema, with navigation, search and Try it out. Every page is prerendered, so it reads without JavaScript and search engines see all of it.

Serve docs/dist/ from any static host. To host the site under a path of your domain, pass the path and the origin to the build, which also writes them into the sitemap:

npm run build -- --base /docs/ --origin https://example.com

Describe the site in the configuration

Instead of listing the files on the command line, list them in apigenie.yaml, with a title for the site and for each API:

version: '1.0'
commands:
  generate:
    docs:
      title: Acme APIs
      documents:
        - file: api/openapi.yaml
          id: shop
          title: Shop API
        - file: api/events.asyncapi.yaml
          id: events
apigenie-generator docs -o docs

The id of a document is its path on the site, so links to it survive when the file moves.

Add the changelog of each API

With --changelog, each API gets a page of the changes its consumers care about, built from the git history of its file as apigenie changelog builds it. Configure the revisions to list releases instead of commits:

commands:
  generate:
    docs:
      changelog:
        revisions: tags
        tag_pattern: 'v*'
        unreleased: true

Translate the documentation

apigenie i18n extracts the texts of a document for translators, and the generator builds a copy of the site per locale, with a locale switcher:

apigenie i18n extract openapi.yaml --output i18n-en.json
# translators turn i18n-en.json into i18n-pl.json, keeping the keys
apigenie i18n check openapi.yaml --translations i18n-pl.json
apigenie-generator docs openapi.yaml --i18n pl=i18n-pl.json -o docs

i18n check fails until every text is translated, which suits CI. When the document changes, i18n sync keeps the translations of the texts that didn’t change and lists the new ones; see i18n.

Or put a reference into your own page

When the API documentation belongs inside a portal or a product site, use the doc components directly. They are standard custom elements, so they work in plain HTML, a CMS or any framework:

npm install @mykulyak/apigenie-docs
<script type="module">
  import "@mykulyak/apigenie-docs";
</script>

<apg-api-reference spec-url="/openapi.yaml"></apg-api-reference>

<apg-api-reference> renders a whole reference. For a page of your own design, use its parts: <apg-operation>, <apg-schema>, <apg-try-it> and the others, inside an <apg-spec> that loads the document once. The doc components page shows them, and their look follows CSS custom properties and ::part().

Next steps