Compartir tecnología

Apispec, una biblioteca de Python para generar especificaciones OpenAPI (Swagger)

2024-07-12

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

Tabla de contenido

01¿Qué es APIspec?

¿Por qué elegir Apispec?

Instalacion y configuracion

02Uso básico de Apispec

Genere documentación API sencilla

1. Cree una instancia de Apispec

2. Definir rutas y vistas API

3. Agregar ruta a Apispec

Integrar Flask y APIspec

1. Instale Flask y Flask-Apispec

2. Crea una aplicación Flask

Integra Django y APIspec

1. Instale Django y Django-Rest-Framework

2. Crea proyectos y aplicaciones de Django.

3. Configurar el proyecto Django

4. Definir vistas de Django

5. Configurar URL

6. Generar especificación OpenAPI

03Funciones avanzadas de Apispec

1. Generador personalizado

2. Admite múltiples marcos

3. Generar automáticamente documentos de interfaz.

4. Integrar con herramientas de terceros

04Casos prácticos

1. Introducción al proyecto

2. Estructura del proyecto

3. Instalar dependencias

4. Definir el modelo

5. Definir vistas y serialización.

6. Definir la aplicación principal.

7. Ejecute la aplicación y vea la documentación.

Visite http://localhost:5000/swagger/ para ver la documentación de API generada.

05Mejores Prácticas

06 Resumen


01¿Qué es APIspec?

Introducción a las especificaciones API

Apispec es una biblioteca de Python para generar especificaciones OpenAPI (Swagger). Puede ayudar a los desarrolladores a generar y mantener automáticamente documentos API y proporcionar descripciones de interfaz intuitivas y detalladas. A través de Apispec, podemos convertir fácilmente la cadena de documentación de una función o clase de Python en un documento que cumpla con la especificación OpenAPI, lo que reduce la molestia de escribir documentación manualmente.

¿Por qué elegir Apispec?

  • Simple y fácil de usar: Apispec proporciona una API simple y fácil de usar para que pueda comenzar rápidamente.

  • Flexible y potente: Admite múltiples marcos (como Flask, Django) y extensiones, lo que le permite personalizar la generación de documentos según sea necesario.

  • automatización: Reduzca las operaciones manuales y los costos de mantenimiento generando y actualizando documentos automáticamente.

Instalacion y configuracion

Antes de comenzar a usar Apispec, primero debemos instalarlo. Puedes instalarlo usando pip:

pip install apispec

Dirección del proyecto Github:

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

02Uso básico de APIspec

Veamos el uso básico de Apispec a través de algunos ejemplos simples.

Genere documentación API sencilla

1. Cree una instancia de 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. Definir rutas y vistas 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. Agregar ruta a 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. )

Integrar Flask y APIspec

1. Instale Flask y Flask-Apispec

pip install Flask Flask-Apispec

2. Crea una aplicación 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()

Integra Django y APIspec

1. Instale Django y Django-Rest-Framework

pip install django djangorestframework

2. Crea proyectos y aplicaciones de Django.

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

3. Configurar el proyecto Django

Agregue rest_framework y apispec en settings.py:

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

4. Definir vistas de Django

En miaplicación/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

En miaplicación/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. Generar especificación OpenAPI

En administrar.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())

03Funciones avanzadas de APIspec

1. Generador personalizado

APIspec proporciona un mecanismo de extensión flexible que le permite personalizar los generadores. Puede implementar su propia lógica de generación heredando y extendiendo la clase base proporcionada por 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. Admite múltiples marcos

Apispec admite una variedad de marcos Python populares, como Flask, Django, Falcon, etc. Puede elegir los marcos y complementos adecuados según sus necesidades y generar rápidamente documentos API.

3. Generar automáticamente documentos de interfaz.

Apispec puede generar automáticamente documentos de interfaz basados ​​en la cadena de documentación de una función o clase, lo que reduce la carga de trabajo de escribir documentos manualmente.

  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. Integrar con herramientas de terceros

Apispec se puede integrar con muchas herramientas de terceros, como Swagger UI, ReDoc, etc., para proporcionar funciones de prueba y visualización de documentos de interfaz intuitiva.

  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ácticos

Cree un sistema completo de documentación API

1. Introducción al proyecto

Supongamos que tenemos un sistema de gestión de usuarios simple y necesitamos documentar su API. Nuestra API incluye operaciones de adición, eliminación, modificación y consulta de usuarios, así como algunas funciones básicas de autenticación de identidad.

2. Estructura del proyecto

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

3. Instalar dependencias

Agregue dependencias en requisitos.txt:

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

Ejecute el siguiente comando para instalar dependencias:

pip install -r requirements.txt

4. Definir el modelo

Defina el modelo de usuario en 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. Definir vistas y serialización.

Defina serializadores de usuario en 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.

Definir vistas en 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. Definir la aplicación principal.

En aplicación.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. Ejecute la aplicación y vea la documentación.

Inicie la aplicación ejecutando el siguiente comando:

python app.py

Visite http://localhost:5000/swagger/ para ver la documentación de API generada.

05Mejores prácticas

1. Mantenga la documentación y el código sincronizados

Asegúrese de que la documentación esté siempre sincronizada con el código para evitar inconsistencias entre la documentación y la API real. Puede utilizar herramientas de CI/CD para generar e implementar documentación automáticamente.

2. Utilice anotaciones y decoradores.

Al utilizar comentarios y decoradores, la documentación puede volverse más concisa y legible. Por ejemplo, utilice el decorador @doc de Flask-Apispec para agregar información de documentación a una función de vista.

3. Definir parámetros y respuestas globales.

Para los parámetros y respuestas de uso común, se pueden definir parámetros globales y plantillas de respuesta en Apispec para reducir el 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. Revisar y actualizar periódicamente la documentación.

Revise y actualice periódicamente la documentación para garantizar su precisión e integridad. Esto se puede lograr estableciendo un ciclo de revisión de documentos o introduciendo un proceso de revisión de documentos.

Para obtener más funciones y uso detallado, consulte la documentación oficial:

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

06resumen

A través de este artículo, creo que tiene una comprensión básica y un dominio de Apispec. Desde el uso básico hasta funciones avanzadas, pasando por casos prácticos y mejores prácticas, presentamos de manera integral cómo usar Apispec para generar y mantener documentos API.

Espero que puedas aplicar este conocimiento a proyectos reales y agregar un toque de brillo a tu API.

Perfil personal

Se ha dedicado a la investigación de tecnología durante más de 30 años y domina varios lenguajes como java, linux, javascript, php, css, etc. Ha realizado muchas contribuciones en el campo del código abierto. Estación de documentación para desarrolladores para compartir algunos problemas en el desarrollo de tecnología para referencia futura.

Mi informacion de contacto

Correo