OpenAPI Parameters

Documentação

Já usamos parâmetros antes para definir o que a requisição deve enviar e validá-los.

Os parâmetros podem ser para:

• path - Usado junto com Path Templating , onde o valor do parâmetro é, na verdade, parte da URL da operação. Isso não inclui o host ou o caminho base da API. Por exemplo, em /items/{itemId}, o parâmetro path é itemId.
• query - Parâmetros que são anexados à URL. Por exemplo, em /items?id=###, o parâmetro query é id.
• header (pouco usado) - Cabeçalhos personalizados que são esperados como parte da solicitação.
• cookie (pouco usado) - Passa um valor de cookie específico para a API.

Vale a pena saber que existem header e cookie, mas não vamos focar nisso pois raramente irá ver isso e acabará esquecendo rápido. Quando necessário aprofunde o estudo nisso.

Não confunda query aqui com a query de SQL, não é a mesma coisa.

O que é obrigatório em cada parâmetros?

• in (string) - O tipo do parâmetro e pode ser query, path, header ou cookie.
• name (string, case sensitive) - Precisa ser o mesmo nome utilizado do objeto Path.
• requerid (boolean) se o in for path obrigatórialmente precisa ser true. Se for os demais pode o pode ser opcional sendo que o default é false.

Temos outras coisas que não são obrigatórios informar mas podems ser úteis.

• description (string) uma breve descrição do parâmetro.
• deprecated (boolean) default é false.
• allowEmptyValue (boolean) e será removido no futuro.

Podemos ter propriedades adicionais aplicadas aos parâmtros em relação como a serialização é feita, mas também são muito pouco utilizadas. Geralmente manter simples as coisas acaba sendo a melhor escolhe e fica mais fácil de manter. O dia que não for suficienteo básico procure o que tem para ajudar.

Query Parameters

Esse são os parâmetros que vem depois do path depois do ?.

Vou colocar inicialmente a spec que vamos trabalhar e fazer os comentários dentro dela para aprendizado.

Vamos especificar 2 parametros em /v1/customers.

openapi: 3.0.2
info:
####
 # Removido diminuir o código
####
paths:
  /v1/customers:
    get:
      # Ao acessar esse path estamos esperando dois parâmetros
      parameters:
        - name: pageNumber
          in: query
          description: Page number
          schema: # ATENÇÃO SOBRE O QUE VOU DIZER LÁ EMBAIXO.
            type: integer
            format: int32
            default: 1
            # Aqui o required também é false, mas existe um valor default 1
        - name: pageSize
          in: query
          required: false # esse ja é o padrão
          schema:
            type: integer
            format: int32
### ...
components:
### ...

O schema não é obrigatório, mas é altamente recomendado. Se você omitir o schema, a documentação do OpenAPI não terá informações sobre o tipo de dado esperado para o parâmetro, o que pode confundir os consumidores da API. Isso pode gerar suposições erradas, como enviar uma string para um parâmetro que deveria ser um número.

Se fossemos consumir esse path precisaríamos passar algo assim https://dev.example.com/v1/customers?pageNumber=5. Se não passassemos nada https://dev.example.com/v1/customers seria a mesma coisa que fazer https://dev.example.com/v1/customers?pageNumber=1

Poderíamos passar os dois parâmtros https://dev.example.com/v1/customers?pageNumber=4pageNumber=2&pageSize=10.

Os parâmetros query são separados po &.

Então agora vamos melhorar e reaproveitar isso e fazer para o beer também, então teríamos isso.

paths:
  /v1/customers:
    get:
      parameters:
        - name: pageNumber
          in: query
          description: Page number
          schema:
            type: integer
            format: int32
            default: 1
        - name: pageSize
          in: query
          required: false # esse ja é o padrão
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: List of Customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPagedList'
  /v1/beers:
    get:
      parameters:
        - name: pageNumber
          in: query
          description: Page number
          schema: # ATENÇÃO SOBRE O QUE VOU DIZER LÁ EMBAIXO.
            type: integer
            format: int32
            default: 1
            # Aqui o required também é false, mas existe um valor default 1
        - name: pageSize
          in: query
          required: false # esse ja é o padrão
          schema:
            type: integer
            format: int32

Veja que temos códigos duplicados ai e poderíamos enxugar isso. Então vamo utilizar o components!. Veja a spec completa.

openapi: 3.0.2
info:
  title: OpenAPI Course
  description: Specification for OpenAPI Course
  termsOfService: http://example.com/terms/
  contact:
    name: John Thompson
    url: https://springframework.guru
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: "1.0"
servers:
- url: https://dev.example.com
  description: Development Server
- url: https://qa.example.com
  description: QA Server
- url: https://prod.example.com
  description: Production Server
paths:
  /v1/customers:
    get:
      parameters:
      # Esse parâmetro será o que temos nesta referência ao fim da especificação
        - $ref: "#/components/parameters/PageNumber"
        - $ref: "#/components/parameters/PageSize"
      responses:
        200:
          description: List of Customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPagedList'
  /v1/beers:
    get:
      parameters:
        - $ref: "#/components/parameters/PageNumber"
        - $ref: "#/components/parameters/PageSize"
      responses:
        200:
          description: List of Beers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeerPagedList'
        404:
          description: No Beers Found
components:
  schemas:
    Address:
      type: object
      properties:
        line1:
          type: string
          example: 123 main
        city:
          type: string
          example: St Pete
        stateCode:
          maxLength: 2
          minLength: 2
          type: string
          description: 2 Letter State Code
          enum:
          - AL
          - AK
          - AZ
          - AR
          - CA
        zipCode:
          type: string
          example: "33701"
    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        firstName:
          maxLength: 100
          minLength: 2
          type: string
          example: John
        lastName:
          maxLength: 100
          minLength: 2
          type: string
          example: Thompson
        address:
          $ref: '#/components/schemas/Address'
      description: customer object
    CustomerList:
      maxItems: 100
      minItems: 1
      type: array
      description: List of Customers
      items:
        $ref: '#/components/schemas/Customer'
    CustomerPagedList:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/CustomerList'
      allOf:
      - $ref: '#/components/schemas/PagedResponse'
    Brewery:
      type: object
      properties:
        name:
          type: string
        location:
          type: string
    Beer:
      type: object
      properties:
        beerName:
          type: string
        style:
          type: string
          enum:
          - ALE
          - PALE_ALE
          - IPA
          - WHEAT
          - LAGER
        price:
          type: number
          format: float
        quantityOnHand:
          type: integer
          format: int32
        brewery:
          $ref: '#/components/schemas/Brewery'
      description: Beer Object
    BeerList:
      type: array
      items:
        $ref: '#/components/schemas/Beer'
    BeerPagedList:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/BeerList'
      allOf:
      - $ref: '#/components/schemas/PagedResponse'
    PagedResponse:
      type: object
      properties:
        pageable:
          $ref: '#/components/schemas/PagedResponse_pageable'
        totalPages:
          type: integer
          format: int32
        last:
          type: boolean
        totalElements:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        number:
          type: integer
          format: int32
        numberOfElements:
          type: integer
          format: int32
        sort:
          $ref: '#/components/schemas/PagedResponse_pageable_sort'
        first:
          type: boolean
    PagedResponse_pageable_sort:
      type: object
      properties:
        sorted:
          type: boolean
        unsorted:
          type: boolean
    PagedResponse_pageable:
      type: object
      properties:
        sort:
          $ref: '#/components/schemas/PagedResponse_pageable_sort'
        offset:
          type: integer
          format: int32
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        paged:
          type: boolean
        unpaged:
          type: boolean
  ############
  parameters:
    PageNumber: # Convenção inicia com maiúsculo
     # AQUI!
      name: pageNumber # mas aqui trabalhamos iniciando com minúsculo
      in: query
      description: Page number
      schema:
        type: integer
        format: int32
        default: 1
    PageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        format: int32

É possível sobreescrever o que importamos do ref.

  /v1/customers:
    get:
      parameters:
      - name: customPageNumber  # Nome sobrescrito aqui
        in: query
        description: Page number
        schema:
          type: integer
          format: int32
          default: 1
      - $ref: "#/components/parameters/PageSize"  # Aqui, sem sobrescrever
      responses:
        200:
          description: List of Customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPagedList'

Dica, matenha o mesmo no name para não confundir e caso necessário sobreescreva como mostrado acima.

Procure manter um padrão para suas nomemclaturas. Por exemplo se quisessemos fazer #/components/parameters/pageSize" poderíamos também para saber que esse será o mesmo nome que recebido.

Path Parameters (URL Parameters)

Podemos especificar um recurso dentro da própria URI definindo a partir do path. Obviamente que se essa variável faz parte da da URI então precisa ser passado e por isso deve ser required: true.

Os parâmetros definidos no path devem ser indicado dentro de chaves ex: {itemId} e o name do objeto de parâmetro deve ser exatamente o mesmo

paths:
  /v1/customers:
    get:
      parameters:
        - $ref: "#/components/parameters/PageNumber"
        - $ref: "#/components/parameters/PageSize"
      responses:
        200:
          description: List of Customers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPagedList'
  /v1/customers/{customerId}:
    get:
      parameters:
        - name: customerId # Observe que é o mesmo nome
          in: path # <<<<
          required: true
          description: Customer Id
          schema:
            type: string
            # Vamos utilizar uma formatação para essa string utilizando uuid
            # uuid é algo assim: a48da5c1-9311-44a4-8d2a-bf4eeeb4cf04
            format: uuid
      responses:
        '200':
          description: Found Customer
          content:
            application/json:
              schema:
                # reaproveitamos o customer não a lista.
                $ref: '#/components/schemas/Customer'

Agora vamos melhorar isso e criar para beer também e colocar no components. Ao invés de usar beerId e CustomerId vamos usar somente ID.

openapi: 3.0.2
info:
#...
paths:
  /v1/customers/{Id}:
    get:
      parameters:
        - $ref: '#/components/parameters/Id'  
      responses:
        '200':
          description: Found Customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'

  /v1/beer/{Id}:
    get:
      parameters:
        - $ref: '#/components/parameters/Id' #porém isso irá trazer o name Id
      responses:
        '200':
          description: Found Beer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beer'
components:
  schemas:
  #...
  parameters:
  #...
    Id:
      name: Id
      in: path
      required: true
      description: UUID for Id
      schema:
        type: string
        format: uudi