O OpenAPI 3 tem alguns recursos avançados para descrever APIs complexas. Veja como você pode usá-los com o Mintlify.

​
oneOf, anyOf, allOf

Para tipos de dados complexos, o OpenAPI fornece as palavras-chave oneOf, anyOf, e allOf, permitindo que você combine esquemas de certas maneiras. Você pode ler mais sobre essas palavras-chave na documentação do Swagger, mas essencialmente:

  • oneOf funciona como um operador “ou-exclusivo”
  • anyOf funciona como um operador “ou”
  • allOf funciona como um operador “e”
As palavras-chave oneOf e anyOf são tratadas da mesma forma. Descobrimos que, quando as pessoas usam oneOf, elas frequentemente querem dizer anyOf - e geralmente não há diferença significativa para o usuário.
A palavra-chave not não é atualmente suportada.

​
Combinando esquemas com allOf

O Mintlify realiza algum pré-processamento em seu documento OpenAPI para exibir essas combinações complexas de uma maneira legível. Por exemplo, quando você combina dois esquemas de objeto com allOf, o Mintlify combina as propriedades de ambos em um único objeto. Isso se torna especialmente útil ao aproveitar os componentes reutilizáveis do componentsOpenAPI.

org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: An array containing all users in the organization
...
components:
  schemas:
    Org:
      type: object
      properties:
        id:
          type: string
          description: The ID of the organization
​
org_with_users
object

​
Fornecendo opções com oneOf e anyOf

Quando você usa oneOf ou anyOf, o Mintlify exibe as opções em um contêiner com abas. Para dar nomes úteis às suas opções, certifique-se de dar a cada subesquema um campo title. Por exemplo, veja como você pode exibir dois tipos diferentes de endereços de entrega:

delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: The street address of the recipient
        ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: The number of the PO Box
        ...
​
delivery_address
object
​
address_line_1
string

O endereço da rua da residência

​
x-codeSamples

Se seus usuários interagem com sua API usando um SDK em vez de diretamente através de uma solicitação de rede, você pode adicionar exemplos de código ao seu documento OpenAPI, e o Mintlify os exibirá em suas páginas OpenAPI. Você pode definir seus exemplos de código usando a extensão x-codeSamples. Esta propriedade pode ser adicionada dentro de qualquer método de solicitação e tem o seguinte esquema:

​
lang
string
required

A linguagem do exemplo de código.

​
label
string

O rótulo para o exemplo. Isso é útil ao fornecer múltiplos exemplos para um único endpoint.

​
source
string
required

O código-fonte do exemplo.

Aqui está um exemplo de alguns exemplos de código para um aplicativo de rastreamento de plantas, que tem tanto uma ferramenta CLI em Bash quanto um SDK em JavaScript.

paths:
  /plants:
    get:
      ...
      x-codeSamples:
        - lang: bash
          label: List all unwatered plants
          source: |
            planter list -u
        - lang: javascript
          label: List all unwatered plants
          source: |
            const planter = require('planter');
            planter.list({ unwatered: true });
        - lang: bash
          label: List all potted plants
          source: |
            planter list -p
        - lang: javascript
          label: List all potted plants
          source: |
            const planter = require('planter');
            planter.list({ potted: true });

​
x-hidden e x-excluded

Se suas páginas são autogenerated a partir de um documento OpenAPI, mas há alguns caminhos para os quais você não quer criar páginas, você pode excluí-los de ter páginas geradas adicionando a propriedade x-excluded.

Se você quer que as páginas sejam geradas, mas não quer que elas apareçam na navegação, adicione x-hidden.

Você pode adicionar a tag x-hidden ou x-excluded sob caminhos de endpoint ou webhook abaixo do método.

Aqui estão exemplos de como isso ficaria em um documento de esquema OpenAPI para um endpoint ou um caminho de webhook:

"paths": {
  "/plants": {
    "get": {
      "description": "Returns all plants from the store",
      "parameters": { ... },
      "responses": { ... }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "Returns all somewhat secret plants from the store",
      "parameters": { ... },
      "responses": { ... }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Returns all top secret plants from the store (do not publish this endpoint!)",
      "parameters": { ... },
      "responses": { ... }
    }
  }
},
"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook for information about a new plant added to the store",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook for somewhat secret information about a new plant added to the store"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)"
    }
  }
}