No desenvolvimento de software, APIs (Application Programming Interfaces) são fundamentais para permitir a comunicação entre diferentes sistemas e aplicações. A documentação de uma API é igualmente crucial, pois facilita a compreensão e a utilização da API por outros desenvolvedores. No ambiente Apple, especialmente quando se desenvolve para iOS e macOS, o uso de Swift e frameworks como Alamofire para a criação de APIs é comum. Este artigo abordará como criar uma API usando Swift e como documentá-la de forma eficaz.

Exemplos:

Criando uma API com Swift

Primeiro, vamos criar uma API simples que retorna uma lista de usuários. Para isso, usaremos o framework Vapor, que é uma das opções mais populares para desenvolvimento de backend em Swift.

1. Instalação do Vapor:

   Abra o Terminal e execute o seguinte comando para instalar o Vapor:

   brew install vapor/tap/vapor

2. Criando um novo projeto Vapor:

   vapor new MyAPI
   cd MyAPI
   vapor build
   vapor run

3. Definindo o modelo de dados:

   No arquivo Models/User.swift, defina o modelo de dados:

   import Vapor
   
   final class User: Content {
      var id: UUID?
      var name: String
      var email: String
   
      init(name: String, email: String) {
          self.name = name
          self.email = email
      }
   }

4. Configurando as rotas:

   No arquivo routes.swift, adicione a rota para obter a lista de usuários:

   func routes(_ app: Application) throws {
      app.get("users") { req -> [User] in
          return [
              User(name: "John Doe", email: "john@example.com"),
              User(name: "Jane Doe", email: "jane@example.com")
          ]
      }
   }

Documentando a API

Para documentar a API, podemos usar o Swagger, uma ferramenta amplamente utilizada para gerar documentação interativa.

1. Instalando o SwagGen:

   SwagGen é uma ferramenta para gerar documentação Swagger a partir de arquivos YAML. Instale-o via Homebrew:

   brew install swaggen

2. Criando o arquivo de especificação Swagger:

   Crie um arquivo swagger.yaml na raiz do projeto:

   openapi: 3.0.0
   info:
    title: MyAPI
    version: 1.0.0
   paths:
    /users:
      get:
        summary: Get list of users
        responses:
          '200':
            description: A JSON array of user names
            content:
              application/json:
                schema:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      email:
                        type: string

3. Gerando a documentação:

   Execute o SwagGen para gerar a documentação:

   swaggen generate -i swagger.yaml -o ./Docs

Visualizando a documentação

Para visualizar a documentação, você pode usar o Swagger UI. Execute o Swagger UI Docker container:

docker run -p 8080:8080 -e SWAGGER_JSON=/mnt/swagger.yaml -v $(pwd)/swagger.yaml:/mnt/swagger.yaml swaggerapi/swagger-ui

Abra o navegador e acesse http://localhost:8080 para ver a documentação interativa da sua API.