Documentação de API na Plataforma Tsuru: Tutorial Prático com Swagger e OpenAPI

Introdução à Plataforma Tsuru e Sua API

A Tsuru é uma plataforma de Platform as a Service (PaaS) open-source, baseada em Docker, que oferece uma API abrangente para gerenciar aplicações, serviços e planos. Neste tutorial, vamos explorar como documentar essa API usando as especificações Swagger e OpenAPI, facilitando o desenvolvimento e a integração.

Conceitos Essenciais: Swagger e OpenAPI

Swagger, agora conhecido como OpenAPI, é um padrão para descrever APIs RESTful de forma estruturada. Ele permite definir endpoints, parâmetros, respostas e modelos de dados em arquivos legíveis por máquina, habilitando a geração automática de documentação interativa e ferramentas de cliente. A Tsuru utiliza o Swagger 2.0, com os arquivos de especificação localizados no diretório docs/reference/ do projeto, incluindo api.yaml, router_api.yaml e service_api.yaml.

Estrutura dos Documentos de API da Tsuru

Os documentos de API da Tsuru são escritos em formato YAML, aderindo à especificação Swagger 2.0. Uma definição completa inclui as seguintes seções principais:

Informações Gerais

A seção inicial define metadados como título, descrição e versão:


swagger: "2.0"
info:
  title: Tsuru API
  description: API para gerenciamento da plataforma PaaS Tsuru
  version: "2.5.1"

Para atualizar a versão, utilize o comando make release version=X.Y.Z no repositório.

Protocolos e Segurança

A especificação declara os protocolos suportados (HTTP/HTTPS) e o método de autenticação:


schemes:
  - https
securityDefinitions:
  TokenAuth:
    type: apiKey
    name: Authorization
    in: header

<p>A autenticação requer o cabeçalho <code>Authorization: Bearer <token></code> em cada solicitação.</p>

<h3>Caminhos e Operações</h3>
<p>A parte central do documento descreve os endpoints da API. Exemplo para serviços:</p>

paths:
  /api/v1/services:
    get:
      operationId: ListAllServices
      summary: Recupera todos os serviços disponíveis
      produces:
        - application/json
      responses:
        "200":
          description: Lista de serviços
          schema:
            $ref: "#/definitions/ServiceCollection"
      tags:
        - services
      security:
        - TokenAuth: []

<p>Cada caminho pode ter múltiplos métodos HTTP, com detalhes sobre parâmetros, respostas e autenticação.</p>

<h3>Definições de Modelos de Dados</h3>
<p>Os modelos de dados reutilizáveis estão na seção <code>definitions</code>:</p>

definitions:
  ServiceCollection:
    type: array
    items:
      $ref: "#/definitions/ServiceItem"
  ServiceItem:
    type: object
    properties:
      identifier:
        type: string
      plan_details:
        type: array
        items:
          type: string

<p>Essas definições são referenciadas em operações via <code>$ref</code> para consistência.</p>

<h2>Gerando e Utilizando a Documentação</h2>

<h3>Obtendo o Código-Fonte</h3>
<p>Clone o repositório da Tsuru para acessar os arquivos de especificação:</p>

git clone https://github.com/tsuru/tsuru
cd tsuru


<h3>Visualizando Documentos Interativos com Swagger UI</h3>
<p>Para explorar a documentação de forma interativa:</p>
<ol>
  <li>Baixe o Swagger UI:
    git clone https://github.com/swagger-api/swagger-ui
  </li>
  <li>Copie o arquivo <code>api.yaml</code> para o diretório <code>dist</code> do Swagger UI.</li>
  <li>Edite <code>dist/index.html</code>, alterando a URL do arquivo de especificação para <code>api.yaml</code>.</li>
  <li>Abra <code>dist/index.html</code> em um navegador para visualizar a documentação.</li>
</ol>

<h3>Gerando Clientes de API Automaticamente</h3>
<p>Use ferramentas como Swagger Codegen para criar clientes em várias linguagens. Exemplo para Python:</p>

swagger-codegen generate -i docs/reference/api.yaml -l python -o tsuru-python-client

<p>Os clientes gerados incluem métodos para todas as operações e modelos de dados definidos.</p>

<h2>Manutenção e Boas Práticas</h2>

<h3>Sincronização entre Código e Documentação</h3>
<p>A Tsuru inclui scripts para validar a consistência. Execute antes de commits:</p>

./misc/check-api-spec.sh

<p>Este script verifica se os handlers da API correspondem aos endpoints documentados.</p>

<h3>Versionamento de APIs</h3>
<p>A Tsuru usa URLs versionadas (ex.: <code>/1.0/</code>, <code>/2.0/</code>) para mudanças compatíveis. Regras:</p>

Alterações retrocompatíveis mantêm a mesma versão.
Mudanças incompatíveis requerem incremento de versão.

Adicionando Exemplos Detalhados

Inclua exemplos de requisição/resposta nos documentos para clareza:


examples:
  application/json:
    - name: "servico-exemplo"
      description: "Descrição do serviço"
      plans: ["basico", "premium"]

Exemplos práticos aceleram a adoção da API por desenvolvedores.

Tags: Tsuru Swagger openapi API-Documentation YAML

Publicado em 6-22 02:58

Doido Dev