# Publish API documentation

Source: https://apigenie.pl/docs/guides/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](/docs/quickstart) shows how.

## Build a site

Use your own files, or download the Carpet Express
[OpenAPI definition](/samples/carpet-express.openapi-31.yaml) as `openapi.yaml` and
[AsyncAPI definition](/samples/carpet-express.asyncapi.yaml) as `events.asyncapi.yaml`.
These describe a fictional service; their sample endpoints aren't live.

```sh
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](/tools/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:

```sh
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:

```yaml
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
```

```sh
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`](/docs/reference/cli/changelog) builds it. Configure
the revisions to list releases instead of commits:

```yaml
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:

```sh
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](/docs/reference/cli/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:

```sh
npm install @mykulyak/apigenie-docs
```

```html
<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](/tools/doc-components) page shows them, and their
look follows CSS custom properties and `::part()`.

## Next steps

- [apigenie-generator docs](/docs/reference/generator/docs): every option and setting, and the
  format of the bundle.
- [Doc components](/tools/doc-components): the elements and how to theme them.
- [Publish API docs](/use-cases/api-docs): what the documentation covers.