Exemplo de como seria o swagger file do BrasilAPI utilizando OpenAPI v3 e YAML

BrasilAPI_swagger.yaml

openapi: 3.0.0
info:
  title: Brasil API
  description: |
    Acesso programático de informações é algo fundamental na comunicação entre sistemas mas, para nossa surpresa, uma informação tão útil e pública quanto um CEP não consegue ser acessada diretamente por um navegador por conta da API dos Correios não possuir CORS habilitado.

    Dado a isso, este projeto experimental tem como objetivo centralizar e disponibilizar endpoints modernos com baixíssima latência utilizando tecnologias como Vercel Smart CDN responsável por fazer o cache das informações em atualmente 23 regiões distribuídas ao longo do mundo (incluindo Brasil). Então não importa o quão devagar for a fonte dos dados, nós queremos disponibilizá-la da forma mais rápida e moderna possível.
    
    Recursos disponíveis
      - CEP
      - DDD
    
  termsOfService: 'https://brasilapi.com.br/'
  version: 1.0.0
  contact:
    name: Felipe Deschamps
    email: filipe@filipedeschamps.com.br
    url: https://filipedeschamps.com.br/
  license:
    name: MIT
    url: https://github.com/filipedeschamps/BrasilAPI/blob/master/LICENSE
tags:
  - name: Brasil API
    description: Transformando Brasil em uma API
    externalDocs:
      description: Saiba mais
      url: https://brasilapi.com.br
paths:
  /cep/v1/{cep}:
    get:
      tags:
        - CEP
      summary: Busca por CEP com múltiplos providers de fallback.
      description: ''
      parameters:
        - name: cep
          description: |
            O CEP (Código de Endereçamento Postal) é um sistema de códigos que visa racionalizar o processo de encaminhamento e entrega de correspondências através da divisão do país em regiões postais. ... Atualmente, o CEP é composto por oito dígitos, cinco de um lado e três de outro. Cada algarismo do CEP possui um significado.
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Success
          content:
            application/json:
              example:
                cep: '89010025'
                state: SC
                city: Blumenau
                neighborhood: Centro
                street: Rua Doutor Luiz de Freitas Melro
        404:
          description: Todos os serviços de CEP retornaram erro.
          content:
            application/json:
              example:
                name: CepPromiseError
                message: Todos os serviços de CEP retornaram erro.
                type: service_error
                errors:
                  - name: ServiceError
                    message: CEP INVÁLIDO
                    service: correios
                  - name: ServiceError
                    message: CEP não encontrado na base do ViaCEP.
                    service: viacep
  /cities/v1/ddd/{ddd}:
    get:
      tags:
        - DDD
      summary: Retorna estado e lista de cidades por DDD
      description: ''
      parameters:
        - name: ddd
          description: |
            DDD significa Discagem Direta à Distância. É um sistema de ligação telefônica automática entre diferentes áreas urbanas nacionais. O DDD é um código constituído por 2 dígitos que identificam as principais cidades do país e devem ser adicionados ao nº de telefone, juntamente com o código da operadora.
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Success
        404:
          description: Todos os serviços de DDD retornaram erro.