API Docs Generator

Turn an OpenAPI/Swagger spec (JSON or YAML) into readable HTML or Markdown docs.

OpenAPI / Swagger spec

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.2.0
  description: Manage books and authors in the Bookstore.
servers:
  - url: https://api.bookstore.example.com/v1
tags:
  - name: Books
    description: Browse and manage books
paths:
  /books:
    get:
      tags: [Books]
      summary: List books
      parameters:
        - name: q
          in: query
          description: Search by title or author
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        '200':
          description: A page of books
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Book' }
    post:
      tags: [Books]
      summary: Add a book
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NewBook' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Book' }
        '422': { description: Validation error }
  /books/{id}:
    get:
      tags: [Books]
      summary: Get a book
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer }, description: Book ID }
      responses:
        '200':
          description: The book
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Book' }
        '404': { description: Not found }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  schemas:
    NewBook:
      type: object
      required: [title, author]
      properties:
        title: { type: string, example: Clean Code }
        author: { type: string, example: Robert C. Martin }
        published: { type: string, format: date }
        tags: { type: array, items: { type: string } }
    Book:
      allOf:
        - $ref: '#/components/schemas/NewBook'
        - type: object
          properties:
            id: { type: integer, example: 42 }
            createdAt: { type: string, format: date-time }

…or drop openapi.yaml / swagger.json

API Docs Generator

More API & HTTP tools