Skip to main content

Estrutura OpenAPI

Visão Geral​

A seguir são apresentados os conceitos mais comuns da estrutura da especificação OpenAPI, em formato YAML. Por ser uma evolução da versão Swagger, a maioria dos conceitos é válida para ambos os formatos, diferenciando apenas a estrutura. A estrutura do formato Swagger foge do escopo desta documentação, bem como os conceitos mais avançados do OpenAPI. Para mais detalhes sobre a estrutura da especificação, verifique as documentações oficiais do OpenAPI e da versão legada Swagger.

Cabeçalho​

Cabeçalho informando o tipo de especificação de API utilizado. Esse campo é obrigatório em todas as especificações.

  • openapi: Obrigatório. Apresenta a informação da versão da especificação OpenAPI utilizada no documento.

Exemplo:

openapi: 3.0.0

Informações básicas​

Bloco com informações básicas e metadados da API, como nome, versão, licenças de software, termos de serviço, informações de contato, entre outros.

  • info: Obrigatório. Merecem destaque os campos:
    • title: Obrigatório. Nome ou título da API.
    • version: Obrigatório. Versão da especificação da API. Comumente utilizado para expressar a versão da API disponibilizada para os consumidores. Normalmente utiliza-se o formato do padrão de versionamento semântico (Semantic Versioning ou SemVer), correlacionado à versão da API cadastrada no DHuO.

Exemplo:

info:
  title: Petstore API
  version: 1.2.0

Servidores​

Bloco opcional com informações dos endereços dos servidores de hospedagem da API. No contexto do DHuO aqui são colocados os endereços dos API Gateways onde as APIs serão implantadas, para conhecimento dos consumidores. Para saber mais sobre API Gateways, acesse a seção Gateways da Administração do API Manager.

  • servers: Bloco opcional com a lista de servidores. Merecem destaque os campos:
    • url: Obrigatório. URL do servidor de destino.

Exemplo:

servers:
  - url: https://dev.petstore.io
  - url: https://petstore.io

Mecanismos de segurança​

Bloco opcional sobre quais mecanismos de segurança podem ser usados na API. Esse bloco pode estar na raiz do documento, indicando tipos de autenticação globais válidos para todos os recursos e operações da API ou dentro das configurações específicas de cada operação. Caso esteja presente em ambos os níveis, as configurações no nível de operação têm precedência e serão as consideradas para a operação. Os mecanismos de segurança são declarados na seção de componentes reutilizáveis, descrito abaixo.

  • security: Bloco opcional com a lista de mecanismos de segurança válidos. Para cada mecanismo de segurança, informa-se:
    • "name": Obrigatório. Nome do mecanismo de segurança cadastrado na seção securitySchemes dos componentes reutilizáveis.
      • "scopes": Lista de escopos necessários para executar o mecanismo de segurança. Caso o tipo de autenticação seja apikey, informar uma lista vazia.

Exemplo security de apikey e oauth2 no escopo global da API:

security:
  myApiKeyAuth: []
  myOauth2Auth:
    - write:pets
    - read:pets

Exemplo security de apikey e oauth2 no escopo da operação GET do recurso /pets:

paths:
  /pets:
    get:
      security:
        myApiKeyAuth: []
        myOauth2Auth:
          - read:pets

Caminho dos recursos​

Bloco com as definições dos caminhos (endereços, paths) para acessar os recursos e operações da API. Caso os paths contenham parâmetros dinâmicos (path parameters), como, por exemplo, ids, eles são representados no formato {parameter_name}. Exemplo: /pets/{petId}.

  • paths: Obrigatório. Merecem destaque os campos:
    • "path": Obrigatório. Caminho para o recurso da API. Deve começar com o caractere /. Cada path, contém, entre outras propriedades:
      • summary: Resumo opcional das operações oferecidas pelo path.
      • parameters: Lista de configurações de parâmetros no escopo geral do path, comuns a todas as operações dele. As configurações de um parâmetro serão detalhadas adiante.
      • "operations": Método HTTP correspondente à operação disponível na API. Valores possíveis: get, post, put, patch, delete, options, head, trace. As configurações de uma operação serão detalhadas adiante.

Exemplo:

paths:
  /pets:
    summary: List pets
    parameters:
      - # parameter 1 config
      - # parameter 2 config
    get:
      # get operation config

Parâmetros​

Bloco com as definições de parâmetros, incluindo o nome e a localização de envio deles. Esses parâmetros podem ser parâmetros de path, parâmetros de consulta (query strings), cabeçalhos (headers) ou cookies. Merecem destaque os campos:

  • name: Obrigatório. Nome do parâmetro.
  • in: Obrigatório. Localização do parâmetro. Valores possíveis: path, query, header, cookie.
  • description: Descrição opcional do parâmetro.
  • required: Informa se o parâmetro é obrigatório.
  • deprecated: Informa se o parâmetro está depreciado.
  • schema: Bloco com as propriedades do schema, informando o tipo e outras informações relevantes. Os campos de configuração de um schema serão detalhadas adiante, na seção de componentes reutilizáveis. Para este momento, a estrutura mínima obrigatória é o campo type.

Exemplos de parâmetros de path, header, query string e cookie:

parameters:
  - name: petId
    in: path
    description: Pet identification
    required: true
    schema:
      type: number

  - name: fullData
    in: query
    description: Return all pet data. Deprecated
    deprecated: true
    schema:
      type: boolean

  - name: X-Token
    in: header
    description: Auth token
    required: true
    schema:
      type: string

  - name: preferences
    in: cookie
    description: data stored in cookie
    schema:
      type: string

Operações (métodos)​

Bloco com as informações de entrada e saída para consumo da operação representada por um método HTTP suportado em um recurso da API. Merecem destaque os campos:

  • summary: Resumo opcional sobre o funcionamento da operação.
  • tags: Lista de tags opcionais para agrupamento de operações da API.
  • operationId: Identificador único, opcional, para a operação.
  • deprecated: Informa se a operação está depreciada.
  • parameters: Lista de configurações de parâmetros específicos da operação. As configurações de um parâmetro seguem a mesma estrutura detalhada anteriormente para o cadastro de parâmetros gerais de path.
  • requestBody: Bloco opcional de configurações da estrutura que será enviada pelo consumidor no corpo da requisição da API (payload). Dentre os campos, destacamos os mais comuns da definição de um requestBody:
    • description: Descrição opcional do payload.
    • required: Informa se o payload é obrigatório.
    • content: Estrutura do conteúdo no formato de mapa contendo o tipo de conteúdo e sua estrutura. Caso a operação da API possibilite receber dados em mais de um formato (por exemplo, JSON e XML), é possível informar mais de um tipo de conteúdo.
      • "contentType": Para APIs REST o mais comum é o tipo application/json. Configurações mais comuns:
        • schema: Bloco com as propriedades do schema, informando o tipo e outras informações relevantes. Os campos de configuração de um schema serão detalhadas adiante, na seção de componentes reutilizáveis.
  • responses: Obrigatório. Bloco contendo as definições de possíveis respostas retornadas pela operação no formato de mapa contendo o código de retorno e sua estrutura.
  • "status_code": Código de retorno, no formato texto, ou o valor fixo default para definições genéricas. Os códigos de retorno correspondem à especificação de códigos HTTP, indicando o status da execução. Alguns exemplos: 200 para sucesso, 400 para erros na requisição do consumidor, 500 para erros ocorridos no servidor da API, entre outros.
    • description: Obrigatório. Descrição do retorno.
    • headers: Parâmetros retornados no cabeçalho (header) na resposta. Mapa contendo o nome do header e as informações correspondentes. As configurações de um parâmetro seguem a mesma estrutura detalhada anteriormente para o cadastro de parâmetros gerais de path, porém sem os campos namee in.
    • content: Estrutura do conteúdo no formato de mapa contendo o tipo de conteúdo e sua estrutura. Caso a operação da API possibilite receber dados em mais de um formato (por exemplo, JSON e XML) é possível informar mais de um tipo de conteúdo.
    • "contentType": Para APIs REST o mais comum é o tipo application/json. Configurações mais comuns:
      • schema: Bloco com as propriedades do schema, informando o tipo e outras informações relevantes. Os campos de configuração de um schema serão detalhadas adiante, na seção de componentes reutilizáveis.

Exemplo:

paths:
  /pets:
    post:
      summary: Add a new pet to the store
      tags:
        - pet
      operationId: addPet
      deprecated: true
      parameters:
        - name: X-Token
          in: header
          description: Auth token
          schema:
            type: string
      requestBody:
        description: Create a new pet in the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
              # or
              type: object
              properties:
                name:
                  type: string
      responses:
        '201':
          description: Successful operation
          headers:
            X-TransactionId:
              description: Transcation ID
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
                # or
                type: object
                properties:
                  name:
                    type: string
        '400':
          description: Invalid input
        'default':
          description: System Error

Componentes reutilizáveis​

Bloco que contém um conjunto de objetos reutilizáveis para diferentes aspectos da especificação. Além das definições dos mecanismos de segurança, é possível reutilizar, por exemplo, schemas de entidades, as definições de estrutura de respostas, parâmetros, headers, exemplos, entre outros. O reuso proporciona especificações mais simples, enxutas e de fácil manutenção. A estrutura básica do bloco contém:

  • components: Bloco opcional com as definições compartilhadas.
    • "component type": Obrigatório. Nome do tipo do componente reutilizável. Valores possíveis: schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links e callbacks.
      • "object name": Nome do objeto de configuração reutilizável. Esse nome será utilizado ao ser refrenciado em outros locais da especificação. Não pode conter espaços
        • "config": Configuração do componente reutilizável. A estrutura de campos vai variar conforme o tipo do componente reutilizável.

Exemplo:

components:
  schemas:
    Pet:
      # schema config
  responses:
    GenericError:
      # response config
  securitySchemes:
    myApiKeyAuth:
      # security scheme config

A seguir são apresentados as propriedades mais comuns da estrutura de mecanismos de segurança (security schemes) e schemas. Para mais detalhes sobre outras configurações, acesse a documentação oficial do OpenAPI.

Security scheme​

Define as configurações de métodos de autenticação que protegem a API. Tipos suportados: HTTP authentication (Basic Authentication), API key, OAuth2 (flows client credentials, authorization code, implicit e password) e OpenID Connect (OIDC).

  • type: Obrigatório. Tipo do security scheme. Valores possíveis: apiKey, http, oauth2, openIdConnect.

Para apikey

  • name: Obrigatório. Nome do parâmetro onde será enviado a API key.
  • in: Obrigatório. Localização onde será enviado a API key. Valores possíveis: header, query, cookie.

Exemplo:

components:
  securitySchemes:
    myApiKeyAuth:
      type: apiKey
      name: X-API-KEY
      in: header

Para http

  • scheme: Obrigatório. Nome do schema de autenticação HTTP. Valores comuns e válidos: basic (para Basic Authentication), bearer (para autenticação utilizando bearer tokens), entre outros.
  • bearerFormat: Caso o scheme seja bearer, opcionalmente informar o formato do bearer token. Valor comum, válido: JWT.

Exemplos Basic Auth e bearer JWT:

components:
  securitySchemes:
    myBasicAuth:
      type: http
      scheme: basic
    myBearerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT

Para oauth2

  • flows: Obrigatório. Objeto com as configurações de cada fluxo OAuth suportado pela API. Cada flow possui sua configuração. Valores possíveis dos flows são: clientCredentials, authorizationCode, implicit, password.
  • authorizationUrl: Obrigatório para authorizationCode e implicit. Authorization URL usada pelo flow.
  • tokenUrl: Obrigatório para clientCredentials, authorizationCode e password. Token URL usada pelo flow.
  • refreshUrl: URL opcional para obter refresh tokens.
  • scopes: Obrigatório. Mapa de escopos OAuth aceitos.
    • "name"": Nome do escopo.
    • "description": Descrição do escopo.

Exemplos OAuth2 flows:

components:
  securitySchemes:
    myOAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://example.com/api/oauth/token
          refreshUrl: https://example.com/api/oauth/refresh-token
          scopes:
            read:pets: read pets info
            write:pets: modify pets in your account
        authorizationCode:
          authorizationUrl: https://example.com/api/oauth/dialog
          tokenUrl: https://example.com/api/oauth/token
          refreshUrl: https://example.com/api/oauth/refresh-token
          scopes:
            read:pets: read pets info
        implicit:
          authorizationUrl: https://example.com/api/oauth/dialog
          refreshUrl: https://example.com/api/oauth/refresh-token
          scopes:
            read:pets: read pets info
        password:
          tokenUrl: https://example.com/api/oauth/token
          refreshUrl: https://example.com/api/oauth/refresh-token
          scopes:
            read:pets: read pets info

Para openIdConnect

  • openIdConnectUrl: Obrigatório. OpenId Connect URL para descoberta de configurações.

Exemplo:

components:
  securitySchemes:
    myOpenIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

Schemas​

Schemas definem a estrutura de dados de um objeto, como seu tipo (booleano, texto, número, lista, objeto), propriedades (caso o tipo não seja primitivo) e outros atributos de acordo com o tipo. Eles são utilizados para definir estruturas de entrada e saída de dados da API, headers, entre outros. Dentre a vasta lista de atributos, destacamos os mais comuns da definição de um schema:

  • type: Obrigatório. Tipo do schema. Valores possíveis: boolean, integer, number, string, array, object.
  • title: Texto opcional descritivo do campo.
  • example: Exemplo de valor possível para o campo.
  • deprecated: Informa se o campo está depreciado.
  • nullable: Informa se o campo pode ser nulo ou vazio.
  • default: Informa o valor padrão (default) para o campo caso não informado.

Para os tipos primitivos

  • enum: Lista de valores possíveis para o campo.
  • format: Formato do campo.
  • minimum: Válido para integere number. Valor mínimo aceito.
  • maximum: Válido para integere number. Valor máximo aceito.
  • pattern: Válido para string. Informa uma expressão regular sobre o formato do campo.
  • minLength: Válido para string. Valor mínimo aceito.
  • maxLength: Válido para string. Valor máximo aceito.

Para o tipo array

  • minItems: Quantidade mínima de itens da lista.
  • maxItems: Quantidade máxima de itens da lista.
  • uniqueItems: Informa se os itens da lista devem ser únicos ou aceitar valores repetidos.
  • items: Informa o schema para descrever o tipo de itens aceitos na lista. Pode ser utilizado tanto a definição de um schema quanto a referência para um schema definido nos componentes compartilhados.

Para o tipo object

  • required: Lista de campos da configuração properties que são obrigatórios.
  • properties: Mapa contendo o nome de cada campo do objeto e o schema para descrever o tipo do campo. Pode ser utilizado tanto a definição de um schema quanto a referência para um schema definido nos componentes compartilhados.

Exemplos de schemas de todos os tipos:

components:
  schemas:
    myBooleanField:
      type: boolean
      title: Boolean field
      example: true
      deprecated: true
      nullable: true
      default: true

    myIntegerField:
      type: integer
      title: Integer field
      example: 2
      deprecated: true
      nullable: true
      default: 2
      enum:
        - 2
        - 4
      format: int32
      minimum: 2
      maximum: 4

    myNumberField:
      type: number
      title: Number field
      example: 1000.00
      deprecated: true
      nullable: true
      default: 2000.00
      enum:
        - 1000.00
        - 2000.00
      format: double
      minimum: 1000.00
      maximum: 2000.00

    myStringField:
      type: string
      title: Email string field
      example: john.doe@mail.com
      deprecated: true
      nullable: true
      default: john.doe@mail.com
      enum:
        - john.doe@mail.com
        - jane.doe@mail.com
      format: email
      pattern: ^[a-zA-Z0-9\.\-_]+@mail.com$
      minLength: 10
      maxLength: 50

    myArrayField:
      type: array
      title: Array of strings
      example:
        - Cat
        - Dog
      deprecated: true
      nullable: true
      default:
        - Cat
      minItems: 1
      maxItems: 3
      uniqueItems: true
      items:
        $ref: '#/components/schemas/myStringField'
        # or
        type: string

    myObjectField:
      type: object
      title: Person object
      example:
        id: 1
        name: John Doe
        age: 18
      deprecated: true
      nullable: true
      required:
        - id
        - name
      properties:
        id:
          $ref: '#/components/schemas/myIntegerField'
        name:
          type: string
        age:
          type: integer

Referências​

A utilização de componentes reutilizáveis é feita utilizando referências. Na especificação são aceitáveis tanto referências internas no próprio documento da especificação, quanto referências para arquivos externos. No contexto do DHuO, apenas referências no próprio documento são aceitas.

  • $ref: Obrigatório. Caminho da referência. O caminho interno segue o formato #/components/component_type/object_name, onde:
    • component_type é o do tipo do componente reutilizável. Valores possíveis: schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks.
    • object_name é o nome do objeto de configuração cadastrado.

Nos exemplos de componentes reutilizáveis anteriores, as referências seriam:

$ref: '#/components/schemas/Pet'
$ref: '#/components/responses/GenericError'
$ref: '#/components/securitySchemes/myApiKeyAuth'