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.