Swagger UI

Usage

To include swagger ui javascript interface in a page you can use the swagger_ui or swagger_ui_advanced tags, eg:

1
2
3
4
5
6
7
8
9
10
11

---
title: Petstore Api Reference
---

{% swagger_ui <swagger path> %}

or

{% swagger_ui_advanced <swagger path> %}
<options>
{% endswagger_ui_advanced }

The location of swagger file (<swagger_path>) can be a local file path or a URL.

Use swagger_ui_advanced when you want to pass configuration options that will override the global configuration (see Configuration).
The <options> value must be a valid JSON.

Examples

With a local path:

1

{% swagger_ui ./petstore.yaml %}

With a URL:

1

{% swagger_ui  https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/json/petstore.json %}

With options:

1
2
3
4
5
6

{% swagger_ui_advanced ./petstore.yaml %}
{
  "version": 3,
  "api_explorer": false
}
{% endswagger_ui_advanced }

Configuration

Adjust swagger-ui behavior by updating your _config.yml, below all the default values:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

theme_config:
  swagger_ui:
    version: 2 # choose which swagger-ui version will be used: 2 or 3

    # version 2 specific options
    permalinks: true   # allows having a URL direct access to a group of operations or to an operation and making it unfolded at startup
    api_explorer: true # display or not API explorer functionalities (try out, authenticate, etc.)
    download: Download specification

    # version 3 specific options
    show_extensions: false
    deep_linking: true
    display_operation_id: false
    doc_expansion: 'none'

Be aware that “permalinks” will work as expected if the specification’s operations are defining the operationId key

Demo v2

Demo v3