Você faz esquemas JSON, usa OpenAPI, Swagger para descrever APIs?

Sim, esquemas JSON, OpenAPI e Swagger são frequentemente utilizados para descrever APIs. Os esquemas JSON ajudam a formalizar a estrutura dos dados transmitidos através da API, facilitando a validação e a geração de documentação.

OpenAPI (anteriormente Swagger) é uma especificação para descrever APIs RESTful, permitindo criar documentação compreensível, gerar SDKs para clientes e servidores, bem como testar a API. Por exemplo, com OpenAPI, pode-se descrever todos os endpoints, métodos, parâmetros e modelos de dados.

Exemplo de uma descrição simples de OpenAPI:

openapi: 3.0.0
info:
  title: API de exemplo
  version: 1.0.0
paths:
  /users:
    get:
      summary: Obter lista de utilizadores
      responses:
        '200':
          description: Resposta bem-sucedida
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string