OpenAPI Docs with Swagger UI and Redoc: A Practical Guide

If the API is internal and only your team consumes it, start code-first. Tools like FastAPI, SpringDoc, or tsoa can derive the spec from your annotations, so the contract stays close to the code:

@app.get("/books/{book_id}")
def get_book(book_id: int):
    ...

If frontend, mobile, backend or external partners need to agree on the contract first, write the OpenAPI YAML and publish it to SwaggerHub or Stoplight before generating stubs:

openapi-generator-cli generate -i openapi.yaml -g python-fastapi

Design-first risks drift: the spec turns into a wishlist while the code does something else. Stop that with contract tests (Schemathesis, Pact) in CI. Code-first risks leaking internal models; stop that by returning DTOs, not database entities.

Generate the spec in CI from your code, publish it to a registry like SwaggerHub or Stoplight, and point the deployed docs at the latest version. In GitHub Actions:

name: Generate OpenAPI Spec
on: push
jobs:
  spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python -m app.main --export-openapi > openapi.json
      - run: npx @redocly/cli lint openapi.json
      - run: npx @redocly/cli build-docs openapi.json -o docs/

Lint the spec on every PR with npx @redocly/cli lint openapi.yaml to catch schema violations, missing responses and broken references. Publish it as a build artifact, deploy docs alongside the API, and then verify the API against the spec by running the command below.

schemathesis run openapi.json --base-url http://localhost:8000

Describe authentication under components/securitySchemes and then apply it to each operation. The first block shows a Bearer JWT scheme.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

For API keys, use type: apiKey and tell clients which header to send.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

OAuth2 needs the flow and scopes declared.

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.example.com/oauth/authorize
          tokenUrl: https://api.example.com/oauth/token
          scopes:
            read: Read access
            write: Write access

Once you define the schemes, apply them at the operation level.

paths:
  /books:
    get:
      security:
        - BearerAuth: []
    post:
      security:
        - OAuth2: [write]

For JWT tokens in OpenAPI 3.1, stick with the HTTP bearer scheme. The apiKey type still works, but it doesn't fit bearer tokens, because it describes a custom API key rather than a bearer scheme.

Set the spec version in info.version and pick a versioning strategy that your clients can discover:

info:
  title: Book API
  version: 2.1.0

Use semantic versioning: major for breaking changes, minor for new endpoints, patch for fixes. For URL-based versioning, put the version in the servers URL:

servers:
  - url: https://api.example.com/v2

For header-based versioning, add an optional header parameter:

parameters:
  - name: X-API-Version
    in: header
    required: true
    schema:
      type: string
      default: "2"

Document deprecations with deprecated: true on operations:

paths:
  /books/{id}:
    get:
      deprecated: true
      description: Use /v2/books/{id} instead

Maintain both spec versions during migration periods and use Accept header content negotiation, for example Accept: application/vnd.api+json;version=2.

Yes. Use the swagger2openapi CLI or Swagger Editor's built-in converter. Most modern tooling handles 3.0 natively now. Run the conversion and expect a few mechanical changes:

npx swagger2openapi swagger.json -o openapi.json

The host, basePath and schemes fields collapse into a servers array; definitions and responses move to components/schemas and components/responses; and securityDefinitions becomes components/securitySchemes. The global produces and consumes fields go away; each operation now declares its own content negotiation. After that, lint the result with npx @redocly/cli lint openapi.json. For a couple of edge cases, the file type becomes format binary and collectionFormat becomes style and explode parameters, so you may need to adjust them manually.

OpenAPI 3.1 drops the old nullable: true flag and instead uses type: [string, null]. It also rewrites exclusiveMinimum and exclusiveMaximum as numbers rather than booleans:

minimum: 0
exclusiveMinimum: true

With 3.1, that turns into exclusiveMinimum: 0. Binary uploads switch from format: binary to contentEncoding: binary, webhooks get a top-level webhooks field, and license identifiers use SPDX. summary inside $ref is optional, and paths can even be empty for webhooks-only APIs.

Before migrating, lint the spec with redocly lint and convert with npx @redocly/cli@latest convert openapi.yaml --to 3.1. Most tools support 3.1 now, but double-check your generator and parser first.

For file uploads in OpenAPI 3.0, use the format binary on a string property inside a multipart/form-data request body. If you need several files, switch the property to an array of binary strings.

In OpenAPI 3.1, format: binary becomes contentEncoding: binary. For downloads, the response should use the application/octet-stream content type, which means you should also declare a binary string schema for the response body. Images work the same way: declare the content type, such as image/png, and a binary schema.

To cap upload size, add maxLength to the binary field and note the limit in the description, for example 10485760 bytes for 10MB.

Polymorphic types can be modeled with the oneOf, anyOf and allOf keywords. For discriminated unions, use oneOf with a discriminator:

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat'
      discriminator:
        propertyName: type
        mapping:
          dog: '#/components/schemas/Dog'
          cat: '#/components/schemas/Cat'

Define subtypes with the discriminator field:

Dog:
  type: object
  properties:
    type:
      type: string
      enum: [dog]
    breed:
      type: string
  required: [type, breed]

For mixed types, use anyOf:

PropertyValue:
  anyOf:
    - type: string
    - type: number
    - type: boolean
    - type: array
      items:
        $ref: '#/components/schemas/PropertyValue'

For composition without discrimination, use allOf to inherit properties:

Animal:
  allOf:
    - $ref: '#/components/schemas/BaseEntity'
    - type: object
      properties:
        species:
          type: string

For RFC 7807 errors, use the application/problem+json media type and a reusable Problem schema:

components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          default: about:blank
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri

Reference it in error responses:

responses:
  '404':
    description: Book not found
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/Problem'
        examples:
          not_found:
            value:
              type: https://api.example.com/errors/not-found
              title: Book not found
              status: 404
              detail: Book with ID 42 not found
              instance: /books/42

Document common error codes: 400 for validation errors, 401 for missing auth, 403 for insufficient permissions, 409 for conflicts, 422 for semantic validation failures, 429 for rate limiting.

Redocly and Spectral are the two linters I reach for. With Redocly, install the CLI globally (npm install -g @redocly/cli), then run redocly lint openapi.yaml. Add a small ruleset file to enforce your own conventions:

rules:
  operation-operationId-unique:
    severity: error
  operation-summary:
    severity: warn
    max_length: 50

Spectral works the same way: npm install -g @stoplight/spectral-cli, then extend the built-in OAS ruleset and override the ones that matter to you. In GitHub Actions:

- name: Lint OpenAPI
  run: npx @redocly/cli lint openapi.yaml

Validate spec structure: check for missing operationId, undefined $ref targets, missing response schemas, and duplicate path parameters. Auto-fix common issues by running redocly lint --format=json openapi.yaml | jq '.problems[] | select(.ruleId == "operation-summary")' to filter specific rules.