Publishing an OpenAPI spec

OpenAPI is the standard way to describe HTTP APIs in JSON or YAML. Tools can read the spec and generate client SDKs, validation layers, mock servers, and documentation. It is the closest thing the API world has to a source of truth for what your service does.

openapi.yaml

yaml

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
paths:
  /api/v1/books:
    get:
      summary: List books
      parameters:
        - in: query
          name: cursor
          schema: { type: integer, minimum: 0 }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 100 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookListResponse'
components:
  schemas:
    Book:
      type: object
      required: [id, title, author, pages, published]
      properties:
        id: { type: integer }
        title: { type: string }
        author: { type: string }
        pages: { type: integer }
        published: { type: string }
    BookListResponse:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Book' } }
        nextCursor: { type: integer, nullable: true }
        hasMore: { type: boolean }

A minimal slice of the bookstore API described in OpenAPI 3.

after/index.ts

typescript

import swaggerUi from 'swagger-ui-express';
import spec from './openapi.json';

app.get('/openapi.json', (req, res) => res.json(spec));
app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec));

Serve the raw spec and a browsable docs UI from the same service.

With those two lines, any consumer can hit /openapi.json to get the raw spec and /docs to get a browsable interface. Clients can generate SDKs from the spec. Testers can generate mock servers from it. Reviewers can diff it to spot breaking changes before the deploy. One spec, many uses.

Quiz: Quiz

Loading practice…