Compartilhamento de tecnologia

Apispec, uma biblioteca Python para gerar especificações OpenAPI (Swagger)

2024-07-12

한어Русский языкEnglishFrançaisIndonesianSanskrit日本語DeutschPortuguêsΕλληνικάespañolItalianoSuomalainenLatina

Índice

01O que é APIspec?

Por que escolher a Apispec?

Instalação e configuração

02Uso básico do Apispec

Gere documentação simples de API

1. Crie uma instância Apispec

2. Defina rotas e visualizações de API

3. Adicione caminho ao Apispec

Integre Flask e APIspec

1. Instale o Flask e o Flask-Apispec

2. Crie um aplicativo Flask

Integre Django e APIspec

1. Instale Django e Django-Rest-Framework

2. Crie projetos e aplicativos Django

3. Configure o projeto Django

4. Defina visualizações do Django

5. Configurar URL

6. Gerar especificação OpenAPI

Recursos avançados do 03Apispec

1. Gerador personalizado

2. Suporta múltiplas estruturas

3. Gere documentos de interface automaticamente

4. Integre com ferramentas de terceiros

04Casos práticos

1. Introdução ao Projeto

2. Estrutura do projeto

3. Instale dependências

4. Defina o modelo

5. Defina visualizações e serialização

6. Defina a aplicação principal

7. Execute o aplicativo e veja a documentação

Visite http://localhost:5000/swagger/ para visualizar a documentação da API gerada.

05 Melhores Práticas

06 Resumo


01O que é APIspec?

Introdução às especificações de API

Apispec é uma biblioteca Python para gerar especificações OpenAPI (Swagger). Ele pode ajudar os desenvolvedores a gerar e manter automaticamente documentos de API e fornecer descrições de interface intuitivas e detalhadas. Por meio do Apispec, podemos converter facilmente a string de documentação de uma função ou classe Python em um documento que esteja em conformidade com a especificação OpenAPI, reduzindo o problema de escrever documentação manualmente.

Por que escolher a Apispec?

  • Simples e fácil de usar: Apispec fornece uma API simples e fácil de usar, permitindo que você comece rapidamente.

  • Flexível e poderoso: Suporta vários frameworks (como Flask, Django) e extensões, permitindo personalizar a geração de documentos conforme necessário.

  • automação: Reduza operações manuais e custos de manutenção gerando e atualizando documentos automaticamente.

Instalação e configuração

Antes de começarmos a usar o Apispec, precisamos primeiro instalá-lo. Você pode instalá-lo usando pip:

pip install apispec

Endereço do projeto Github:

https://github.com/marshmallow-code/apispec

02Uso básico de APIspec

Vejamos o uso básico do Apispec por meio de alguns exemplos simples.

Gere documentação simples de API

1. Crie uma instância Apispec

  1. from apispec import APISpec
  2.  
  3. spec = APISpec(
  4.     title="My API",
  5.     version="1.0.0",
  6.     openapi_version="3.0.0",
  7.     info=dict(description="This is a sample API"),
  8. )

2. Defina rotas e visualizações de API

  1. def get_user(user_id):
  2.     """
  3.     ---
  4.     get:
  5.       description: Get a user by ID
  6.       parameters:
  7.         - name: user_id
  8.           in: path
  9.           required: true
  10.           schema:
  11.             type: integer
  12.       responses:
  13.         200:
  14.           description: A user object
  15.           content:
  16.             application/json:
  17.               schema:
  18.                 type: object
  19.                 properties:
  20.                   id:
  21.                     type: integer
  22.                   name:
  23.                     type: string
  24.     """
  25.     return {"id": user_id, "name": "John Doe"}

3. Adicione caminho ao Apispec

  1. spec.path(
  2.     path="/users/{user_id}",
  3.     operations=dict(
  4.         get=dict(
  5.             description="Get a user by ID",
  6.             parameters=[
  7.                 {
  8.                     "name": "user_id",
  9.                     "in": "path",
  10.                     "required": True,
  11.                     "schema": {"type": "integer"},
  12.                 }
  13.             ],
  14.             responses={
  15.                 "200": {
  16.                     "description": "A user object",
  17.                     "content": {
  18.                         "application/json": {
  19.                             "schema": {
  20.                                 "type": "object",
  21.                                 "properties": {
  22.                                     "id": {"type": "integer"},
  23.                                     "name": {"type": "string"},
  24.                                 },
  25.                             }
  26.                         }
  27.                     },
  28.                 }
  29.             },
  30.         )
  31.     ),
  32. )

Integre Flask e APIspec

1. Instale o Flask e o Flask-Apispec

pip install Flask Flask-Apispec

2. Crie um aplicativo Flask

  1. from flask import Flask, jsonify
  2. from flask_apispec import FlaskApiSpec, doc, marshal_with
  3. from flask_apispec.views import MethodResource
  4. from marshmallow import Schema, fields
  5.  
  6. app = Flask(__name__)
  7.  
  8. class UserSchema(Schema):
  9.     id = fields.Int()
  10.     name = fields.Str()
  11.  
  12. class UserResource(MethodResource):
  13.     @doc(description='Get a user by ID', tags=['User'])
  14.     @marshal_with(UserSchema)
  15.     def get(self, user_id):
  16.         return {"id": user_id, "name": "John Doe"}
  17.  
  18. app.add_url_rule('/users/<int:user_id>', view_func=UserResource.as_view('user_resource'))
  19. docs = FlaskApiSpec(app)
  20. docs.register(UserResource)
  21.  
  22. @app.route('/swagger/')
  23. def swagger_ui():
  24.     return jsonify(docs.spec.to_dict())
  25.  
  26. if __name__ == '__main__':
  27.     app.run()

Integre Django e APIspec

1. Instale Django e Django-Rest-Framework

pip install django djangorestframework

2. Crie projetos e aplicativos Django

  1. django-admin startproject myproject
  2. cd myproject
  3. django-admin startapp myapp

3. Configure o projeto Django

Adicione rest_framework e apispec em settings.py:

  1. INSTALLED_APPS = [
  2.     ...
  3.     'rest_framework',
  4.     'myapp',
  5.     'apispec',
  6. ]

4. Defina visualizações do Django

Em myapp/views.py:

  1. from rest_framework.views import APIView
  2. from rest_framework.response import Response
  3. from rest_framework.schemas import AutoSchema
  4.  
  5. class UserView(APIView):
  6.     schema = AutoSchema(
  7.         manual_fields=[
  8.             coreapi.Field('user_id', required=True, location='path', schema={'type': 'integer'})
  9.         ]
  10.     )
  11.  
  12.     def get(self, request, user_id):
  13.         """
  14.         Get a user by ID.
  15.         ---
  16.         responses:
  17.           200:
  18.             description: A user object
  19.             content:
  20.               application/json:
  21.                 schema:
  22.                   type: object
  23.                   properties:
  24.                     id:
  25.                       type: integer
  26.                     name:
  27.                       type: string
  28.         """
  29.         return Response({"id": user_id, "name": "John Doe"})

5. Configurar URL

Em myapp/urls.py:

  1. from django.urls import path
  2. from .views import UserView
  3.  
  4. urlpatterns = [
  5.     path('users/<int:user_id>/', UserView.as_view(), name='user-view'),
  6. ]

6. Gerar especificação OpenAPI

Em gerenciar.py:

  1. from apispec import APISpec
  2. from rest_framework.schemas import get_schema_view
  3.  
  4. spec = APISpec(
  5.     title="My API",
  6.     version="1.0.0",
  7.     openapi_version="3.0.0",
  8. )
  9.  
  10. schema_view = get_schema_view(title="My API")
  11. schema = schema_view.get_schema(request=None, public=True)
  12. spec.components.schema('User', schema)
  13. spec.path(path='/users/{user_id}/', operations=schema['paths']['/users/{user_id}/'])
  14.  
  15. print(spec.to_yaml())

03Recursos avançados do APIspec

1. Gerador personalizado

APIspec fornece um mecanismo de extensão flexível que permite personalizar geradores. Você pode implementar sua própria lógica de geração herdando e estendendo a classe base fornecida pelo Apispec.

  1. from apispec import BasePlugin
  2.  
  3. class MyPlugin(BasePlugin):
  4.     def path_helper(self, operations, *, resource, **kwargs):
  5.         operations.update({
  6.             'get': {
  7.                 'description': 'Get a user by ID',
  8.                 'parameters': [
  9.                     {'name': 'user_id', 'in': 'path', 'required': True, 'schema': {'type': 'integer'}}
  10.                 ],
  11.                 'responses': {
  12.                     '200': {
  13.                         'description': 'A user object',
  14.                         'content': {
  15.                             'application/json': {
  16.                                 'schema': {
  17.                                     'type': 'object',
  18.                                     'properties': {
  19.                                         'id': {'type': 'integer'},
  20.                                         'name': {'type': 'string'}
  21.                                     }
  22.                                 }
  23.                             }
  24.                         }
  25.                     }
  26.                 }
  27.             }
  28.         })
  29.  
  30. spec = APISpec(
  31.     title="My API",
  32.     version="1.0.0",
  33.     openapi_version="3.0.0",
  34.     plugins=[MyPlugin()],
  35. )

2. Suporta múltiplas estruturas

Apispec oferece suporte a uma variedade de estruturas Python populares, como Flask, Django, Falcon, etc. Você pode escolher estruturas e plug-ins apropriados de acordo com suas necessidades para gerar rapidamente documentos de API.

3. Gere documentos de interface automaticamente

Apispec pode gerar automaticamente documentos de interface com base na string de documentação de uma função ou classe, reduzindo a carga de trabalho de escrita manual de documentos.

  1. def get_user(user_id):
  2.     """
  3.     ---
  4.     get:
  5.       description: Get a user by ID
  6.       parameters:
  7.         - name: user_id
  8.           in: path
  9.           required: true
  10.           schema:
  11.             type: integer
  12.       responses:
  13.         200:
  14.           description: A user object
  15.           content:
  16.             application/json:
  17.               schema:
  18.                 type: object
  19.                 properties:
  20.                   id:
  21.                     type: integer
  22.                   name:
  23.                     type: string
  24.     """
  25.     return {"id": user_id, "name": "John Doe"}

4. Integre com ferramentas de terceiros

Apispec pode ser integrado com muitas ferramentas de terceiros, como Swagger UI, ReDoc, etc., para fornecer interface intuitiva de exibição de documentos e funções de teste.

  1. from flask import Flask, jsonify
  2. from flask_apispec import FlaskApiSpec
  3.  
  4. app = Flask(__name__)
  5.  
  6. @app.route('/users/<int:user_id>', methods=['GET'])
  7. def get_user(user_id):
  8.     """
  9.     ---
  10.     get:
  11.       description: Get a user by ID
  12.       parameters:
  13.         - name: user_id
  14.           in: path
  15.           required: true
  16.           schema:
  17.             type: integer
  18.       responses:
  19.         200:
  20.           description: A user object
  21.           content:
  22.             application/json:
  23.               schema:
  24.                 type: object
  25.                 properties:
  26.                   id:
  27.                     type: integer
  28.                   name:
  29.                     type: string
  30.     """
  31.     return jsonify({"id": user_id, "name": "John Doe"})
  32.  
  33. docs = FlaskApiSpec(app)
  34. docs.register(get_user)
  35.  
  36. if __name__ == '__main__':
  37.     app.run()

04Casos práticos

Crie um sistema completo de documentação de API

1. Introdução ao Projeto

Suponha que temos um sistema simples de gerenciamento de usuários e precisamos documentar sua API. Nossa API inclui operações de adição, exclusão, modificação e consulta de usuários, bem como algumas funções básicas de autenticação de identidade.

2. Estrutura do projeto

  1. user_management/
  2. ├── app.py
  3. ├── models.py
  4. ├── views.py
  5. ├── serializers.py
  6. └── requirements.txt

3. Instale dependências

Adicione dependências em requisitos.txt:

  1. Flask
  2. Flask-RESTful
  3. Flask-SQLAlchemy
  4. Flask-Migrate
  5. apispec
  6. flask-apispec

Execute o seguinte comando para instalar dependências:

pip install -r requirements.txt

4. Defina o modelo

Defina o modelo do usuário em models.py:

  1. from flask_sqlalchemy import SQLAlchemy
  2.  
  3. db = SQLAlchemy()
  4.  
  5. class User(db.Model):
  6.     id = db.Column(db.Integer, primary_key=True)
  7.     name = db.Column(db.String(80), nullable=False)
  8.     email = db.Column(db.String(120), unique=True, nullable=False)

5. Defina visualizações e serialização

Defina serializadores de usuário em serializers.py:

  1. from marshmallow import Schema, fields
  2.  
  3. class UserSchema(Schema):
  4.     id = fields.Int(dump_only=True)
  5.     name = fields.Str(required=True)
  6.     email = fields.Email(required=True)
  7.

Defina visualizações em views.py:

  1. from flask import request
  2. from flask_restful import Resource
  3. from models import User, db
  4. from serializers import UserSchema
  5.  
  6. class UserResource(Resource):
  7.     def get(self, user_id):
  8.         user = User.query.get_or_404(user_id)
  9.         schema = UserSchema()
  10.         return schema.dump(user)
  11.  
  12.     def post(self):
  13.         schema = UserSchema()
  14.         user = schema.load(request.json)
  15.         db.session.add(user)
  16.         db.session.commit()
  17.         return schema.dump(user), 201
  18.  
  19.     def put(self, user_id):
  20.         user = User.query.get_or_404(user_id)
  21.         schema = UserSchema(partial=True)
  22.         updated_user = schema.load(request.json, instance=user)
  23.         db.session.commit()
  24.         return schema.dump(updated_user)
  25.  
  26.     def delete(self, user_id):
  27.         user = User.query.get_or_404(user_id)
  28.         db.session.delete(user)
  29.         db.session.commit()
  30.         return '', 204

6. Defina a aplicação principal

Em app.py:

  1. from flask import Flask
  2. from flask_restful import Api
  3. from flask_migrate import Migrate
  4. from models import db
  5. from views import UserResource
  6. from flask_apispec import FlaskApiSpec
  7. from flask_apispec.extension import FlaskApiSpec
  8.  
  9. app = Flask(__name__)
  10. app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///users.db'
  11. db.init_app(app)
  12. migrate = Migrate(app, db)
  13. api = Api(app)
  14.  
  15. api.add_resource(UserResource, '/users/<int:user_id>')
  16.  
  17. docs = FlaskApiSpec(app)
  18. docs.register(UserResource)
  19.  
  20. if __name__ == '__main__':
  21.     app.run()

7. Execute o aplicativo e veja a documentação

Inicie o aplicativo executando o seguinte comando:

python app.py

Visite http://localhost:5000/swagger/ para visualizar a documentação da API gerada.

05Melhores Práticas

1. Mantenha a documentação e o código sincronizados

Certifique-se de que a documentação esteja sempre sincronizada com o código para evitar inconsistências entre a documentação e a API real. Você pode usar ferramentas de CI/CD para gerar e implantar documentação automaticamente.

2. Use anotações e decoradores

Ao usar comentários e decoradores, a documentação pode se tornar mais concisa e legível. Por exemplo, use o decorador @doc do Flask-Apispec para adicionar informações de documentação a uma função de visualização.

3. Defina parâmetros e respostas globais

Para parâmetros e respostas comumente usados, parâmetros globais e modelos de resposta podem ser definidos no Apispec para reduzir código repetido.

  1. spec.components.parameter("user_id", "path", schema={"type": "integer"}, required=True)
  2. spec.components.response("User", {
  3.     "description": "A user object",
  4.     "content": {
  5.         "application/json": {
  6.             "schema": {
  7.                 "type": "object",
  8.                 "properties": {
  9.                     "id": {"type": "integer"},
  10.                     "name": {"type": "string"}
  11.                 }
  12.             }
  13.         }
  14.     }
  15. })

4. Revise e atualize regularmente a documentação

Revise e atualize regularmente a documentação para garantir precisão e integridade. Isto pode ser conseguido através da criação de um ciclo de revisão de documentos ou da introdução de um processo de revisão de documentos.

Para mais funções e uso detalhado, consulte a documentação oficial:

https://apispec.readthedocs.io/en/latest

06resumo

Através deste artigo, acredito que você tenha um conhecimento básico e domínio do Apispec. Do uso básico às funções avançadas, passando por casos práticos e melhores práticas, apresentamos de forma abrangente como usar o Apispec para gerar e manter documentos API.

Espero que você possa aplicar esse conhecimento a projetos reais e adicionar um toque de brilho à sua API.

Perfil pessoal

Ele se dedica à pesquisa de tecnologia há mais de 30 anos e é proficiente em diversas linguagens como java, linux, javascript, php, css, etc. estação de documentação do desenvolvedor para compartilhar alguns problemas no desenvolvimento de tecnologia para referência futura.

minhas informações de contato

Correspondência