Se os seus usuários interagem com a sua API usando um SDK em vez de diretamente por meio de uma requisição de rede, você pode usar a extensão x-codeSamples
para adicionar exemplos de código ao seu documento OpenAPI e exibí-los nas suas páginas OpenAPI.
Essa propriedade pode ser adicionada a qualquer método de requisição e tem o seguinte esquema.
O idioma do exemplo de código.
O rótulo do exemplo. Isso é útil ao fornecer vários exemplos para um único endpoint.
O código-fonte do exemplo.
Aqui está um exemplo de exemplos de código para um app de acompanhamento de plantas, que tem tanto uma ferramenta de 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 });