Antora Swagger UI Extension

An Antora extension that integrates the Swagger UI (interactive API explorer) into an Antora site. It does so by providing and registering an AsciiDoc swagger-ui block macro that adds an API explorer for an OpenAPI specification to a page. The Swagger UI dynamically generates interactive documentation for an API defined in the OpenAPI Specification format.

Prerequisites

In order to use this extension, you must be using Node.js 18 and Antora 3.1.0. The following instructions assume you’ve already set up an Antora playbook file (i.e., antora-playbook.yml) to build your site.

To learn about using extensions with Antora, see the Antora extension documentation.

Install

Use the following command to install the extension into your playbook project:

$ npm i @opendevise/antora-swagger-ui-extension

Register

Open your Antora playbook file and register the extension as an entry in the antora.extensions key. Create this key if it doesn’t yet exist in your playbook file.

antora-playbook.yml

antora:
  extensions:
  - '@opendevise/antora-swagger-ui-extension'

This extension automatically registers the swagger-ui block macro extension with Asciidoctor. The extension also patches the head-styles.hbs and footer-scripts.hbs UI templates to load the Swagger UI assets (CSS and JS) as needed.

Usage

The Swagger UI will automatically be loaded on any page that uses the swagger-ui AsciiDoc block macro. Any number of swagger-ui block macros can be used per page.

The target of the macro is an OpenAPI specification file that can be referenced using an Antora resource reference. The specification file must be in either JSON or YAML format and must have the suitable file extension (e.g., .json, .yaml, etc). The file can be resolved from the attachment, example, or partial families. For example:

swagger-ui::attachment$petstore.json[]

or

swagger-ui::api:attachment$specs/petstore.yaml[]

If the file extension is absent or not recognized, the JSON format is assumed.

If you don’t want the specification file to be published, you can make it hidden by prefixing it with an underscore. For example:

swagger-ui::attachment$_petstore.json[]

Alternately, the target of the macro can be a URL. For example:

swagger-ui::https://petstore3.swagger.io/api/v3/openapi.yaml[]

When the target is a URL, that URL is passed directly to the Swagger UI to load. In this case, a file extension is not required (as long as the server still serves the file).

Configure

The swagger-ui block macro supports the following attributes:

• id
  Sets the ID of the insertion slot element in which to insert the explorer. By default, the ID swagger-ui-<n> is used, where <n> is managed as the 1-based index of the explorer on the page. You can use the swagger-ui-number AsciiDoc document attribute to control the start index (e.g., :swagger-ui-number: -1).
• docExpansion
  Controls the docExpansion setting of the explorer. Value values are full, list, and none. The default value is list.

Copyright and License

Copyright (C) 2024-present by OpenDevise Inc. and the individual contributors of this project.

Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0).