@opendevise/antora-swagger-ui-extension/README.md

An Antora extension that integrates the Swagger UI (interactive API explorer) into an Antora site through AsciiDoc syntax extensions.

# Antora Swagger UI Extension

An [Antora](https://antora.org) 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](https://antora.org), see the [Antora extension documentation](https://docs.antora.org/antora/latest/extend/extensions/).

## Install

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

```console
$ 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**

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

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

or

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

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

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

```asciidoc
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](https://www.mozilla.org/en-US/MPL/2.0/) (MPL-2.0).