API Genie

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

Usage

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

Description

The site is built in two steps:

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

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), 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.

Examples

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