# docs

Source: https://apigenie.pl/techdocs/reference/cli-generate_docs

Generate a documentation site from OpenAPI, Swagger 2.0, AsyncAPI, GraphQL and Protobuf files,
several at once.

## Usage

```sh
apigenie-generator docs [...OPTIONS] INPUT...
```

## Description

The site is built in two steps:

1. `apigenie-generator docs` reads the inputs and writes a *docs bundle*: a manifest
   (`apigenie-docs.json`) and, per document and locale, the resolved document (OpenAPI and
   Swagger 2.0, with the files it references bundled in) or the documentation model (AsyncAPI,
   GraphQL and Protobuf), with the git changelog and the example files when asked for. Next to the
   bundle it writes `package.json` and a README: an npm project that depends on the API Genie web
   components, `@mykulyak/apigenie-docs`.
2. `npm install`, then `npm run build` renders the bundle into `dist/`: one HTML page per API,
   operation and schema, prerendered so that it reads without JavaScript and hydrates with it
   (Try it out, search, navigation), with a sitemap, a locale switcher, a changelog page and the
   examples. Serve `dist/` from any static host. `npm run build -- --base /docs/ --origin
   https://example.com` hosts the site under a path and writes absolute URLs into the sitemap.

The CLI never runs Node: the bundle is plain JSON, and `--bundle-only` writes it alone for a site
built by other means, such as a page of your own holding an `<apg-api-reference>` element.

Several inputs of mixed families make one site, each document under its own path. An input that
can't be read is reported with its positions and left out; the others are still written. Files of
the output directory that the bundle doesn't write are left alone.

## Options

| Option | Description |
| --- | --- |
| `-o`, `--output OUTPUT` | The output directory (required). |
| `-c`, `--config CONFIG` | The configuration file: its `commands.generate.docs` section configures the site (below), its `diff` section the severities of the changelog. |
| `--i18n LOCALE=FILE` | A translation file, as [`i18n extract`](/techdocs/reference/cli-i18n) writes it, for a locale. Can be repeated. Every file applies to every input, with the keys of the input's kind (JSON pointers for OpenAPI, Swagger and AsyncAPI, names for GraphQL and Protobuf); a file that translates nothing in an input is a warning. |
| `--changelog` | Adds the changelog of each input from its git history, as [`apigenie changelog`](/techdocs/reference/cli-changelog) computes it. An input outside a repository gets a warning and no changelog. |
| `--package-name NAME` | The name of the generated npm package (`api-docs` by default). |
| `--package-version VERSION` | Its version (`1.0.0` by default). |
| `--bundle-only` | Writes the docs bundle only, without `package.json` and README. |

## Configuration

All keys are optional and sit under `commands.generate.docs`. Paths are relative to the
configuration file.

```yaml
version: '1.0'
commands:
  generate:
    docs:
      title: Acme APIs
      default_locale: en
      prefix_default_locale: false
      changelog:
        revisions: tags
        tag_pattern: 'v*'
        unreleased: true
      documents:
        - file: api/openapi.yaml
          id: shop
          title: Shop API
        - file: proto/orders.proto
          proto_paths: [proto]
          examples:
            - file: examples/create-order.json
              title: Create an order
```

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | string | the first document's title | The title of the site. |
| `default_locale` | string | `en` | The locale of the documents as written. `--i18n` files add the other locales. |
| `prefix_default_locale` | bool | `false` | Whether the default locale's pages get the locale prefix too (`/en/...`). |
| `changelog` | bool or object | `false` | `true` adds the changelog of every document (as `--changelog`); an object also selects the revisions: `revisions` (`commits` or `tags`), `tag_pattern`, `tag_sort` (`version` or `date`), `unreleased`, `from`, `to`, as the options of `apigenie changelog`. |
| `documents` | list | | The inputs, besides those given on the command line: `file`, and optionally `id` (the document's directory in the bundle, by default the file's stem), `title`, `proto_paths` (the directories a .proto file's imports are searched in, before its own) and `examples` (paths, or `{file, title}`). |

## The docs bundle

```
apigenie-docs.json                      the manifest
documents/<id>/document.<locale>.json   the document per locale
documents/<id>/changelog.json           with --changelog
documents/<id>/examples/<file>          example files
package.json, README.md                 unless --bundle-only
```

The manifest holds `apigenieDocs: 1` and `formatVersion: 1` (the version of the format, under
the name all JSON outputs of API Genie use; see
[Compatibility](/techdocs/reference/cli-compatibility)), `title`, `generator`,
`locales` (the default one first), `prefixDefaultLocale` and `documents`, each with `id`,
`family` (`openapi`, `swagger`, `asyncapi`, `graphql` or `protobuf`), `title`, `version`,
`source` (the input's file name), `files` (per locale), and `changelog` and `examples` when
present. Paths are relative to the bundle. Its JSON Schema is
[apigenie-docs-manifest.json](https://apigenie.pl/schemas/apigenie-docs-manifest.json).

## Examples

Next to a GraphQL schema, the `.json`, `.yaml` and `.yml` files of its `<name>_examples`
directory (the examples [`apigenie test`](/techdocs/reference/cli-test) runs) are copied into the
bundle and shown with the schema. Any document can list more under `examples` in the
configuration.

## See also

- [i18n](/techdocs/reference/cli-i18n), which extracts the translation files `--i18n` takes
- [changelog](/techdocs/reference/cli-changelog), whose changelog `--changelog` writes into the bundle
- [configuration](/techdocs/reference/cli-configuration)