Swagger UI Tag Plugin

Interactive API documentation using OpenAPI/Swagger specifications.

Core Attributes

Plugin Name

swagger-ui-tag

Repository

https://github.com/blueswen/mkdocs-swagger-ui-tag

Installation

Bash

pip install mkdocs-swagger-ui-tag

Configuration

YAML

plugins:
  - swagger-ui-tag:
      background: White
      docExpansion: none
      filter: true
      syntaxHighlightTheme: monokai

What It Does

Embeds Swagger UI directly in your documentation pages, allowing users to: - Browse API endpoints interactively - Test API calls directly from docs - View request/response schemas - See example payloads

Usage

Basic Usage

Place your OpenAPI spec in docs:

Text Only

docs/
├── api/
│   └── openapi.json
└── api-reference.md

Embed in markdown:

Markdown

# API Reference

<swagger-ui src="../api/openapi.json" />

With YAML Spec

Markdown

<swagger-ui src="./api-spec.yaml" />

External Specs

Markdown

<swagger-ui src="https://petstore.swagger.io/v2/swagger.json" />

Configuration Options

background

Background color: White or Black

docExpansion

Initial expansion: none, list, or full

filter

Enable search filter: true or false

syntaxHighlightTheme

Code theme: agate, arta, monokai, nord, obsidian, tomorrow-night

OpenAPI Spec Example

Minimal Spec

YAML

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object

Complete Example

YAML

openapi: 3.0.0
info:
  title: User Management API
  description: API for managing users
  version: 2.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v2
    description: Production
  - url: https://staging-api.example.com/v2
    description: Staging

paths:
  /users:
    get:
      summary: List all users
      tags:
        - Users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

    post:
      summary: Create user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        '201':
          description: User created

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

    NewUser:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email

Best Practices

1. Organize with Tags

YAML

paths:
  /users:
    get:
      tags:
        - User Management
  /posts:
    get:
      tags:
        - Content

2. Use Examples

YAML

responses:
  '200':
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
        examples:
          john:
            value:
              id: 1
              name: John Doe
              email: john@example.com

3. Document Parameters

YAML

parameters:
  - name: userId
    in: path
    required: true
    description: The unique identifier of the user
    schema:
      type: integer
      minimum: 1

4. Use Components

Reuse schemas, parameters, and responses:

YAML

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

  parameters:
    limitParam:
      name: limit
      in: query
      schema:
        type: integer

5. Add Descriptions

YAML

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      description: |
        Retrieves detailed information about a specific user.

        This endpoint requires authentication and the user must
        have read permissions.

Tips

Keep specs in version control
Validate specs with tools
Use meaningful operation IDs
Document all status codes
Include authentication details
Provide realistic examples