Partage de technologie

Apispec, une bibliothèque Python pour générer des spécifications OpenAPI (Swagger)

2024-07-12

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

Table des matières

01Qu'est-ce qu'APIspec ?

Pourquoi choisir Apispec ?

Installation et configuration

02Utilisation de base d'Apispec

Générer une documentation API simple

1. Créez une instance Apispec

2. Définir les routes et les vues API

3. Ajouter un chemin vers Apispec

Intégrer Flask et APIspec

1. Installez Flask et Flask-Apispec

2. Créez une application Flask

Intégrer Django et APIspec

1. Installez Django et Django-Rest-Framework

2. Créer des projets et des applications Django

3. Configurer le projet Django

4. Définir les vues Django

5. Configurer l'URL

6. Générer la spécification OpenAPI

03Les fonctionnalités avancées de Apispec

1. Générateur personnalisé

2. Prise en charge de plusieurs frameworks

3. Générez automatiquement les documents d'interface

4. Intégrez des outils tiers

04Cas pratiques

1. Présentation du projet

2. Structure du projet

3. Installer les dépendances

4. Définir le modèle

5. Définir les vues et la sérialisation

6. Définir l'application principale

7. Exécutez l'application et consultez la documentation

Visitez http://localhost:5000/swagger/ pour afficher la documentation de l'API générée.

05Bonnes pratiques

06 Résumé


01Qu'est-ce qu'APIspec ?

Introduction aux APIspecs

Apispec est une bibliothèque Python permettant de générer des spécifications OpenAPI (Swagger). Il peut aider les développeurs à générer et à maintenir automatiquement des documents API et à fournir des descriptions d'interface intuitives et détaillées. Grâce à Apispec, nous pouvons facilement convertir la chaîne de documentation d'une fonction ou d'une classe Python en un document conforme à la spécification OpenAPI, réduisant ainsi les problèmes d'écriture manuelle de la documentation.

Pourquoi choisir Apispec ?

  • Simple et facile à utiliser: Apispec fournit une API simple et facile à utiliser pour que vous puissiez démarrer rapidement.

  • Souple et puissant: Prend en charge plusieurs frameworks (tels que Flask, Django) et extensions, vous permettant de personnaliser la génération de documents selon vos besoins.

  • automatisation: Réduisez les coûts d’opérations manuelles et de maintenance en générant et en mettant à jour automatiquement les documents.

Installation et configuration

Avant de commencer à utiliser Apispec, nous devons d'abord l'installer. Vous pouvez l'installer en utilisant pip :

pip install apispec

Adresse du projet Github :

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

02Utilisation de base d'APIspec

Examinons l'utilisation de base d'Apispec à travers quelques exemples simples.

Générer une documentation API simple

1. Créez une instance 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. Définir les routes et les vues 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. Ajouter un chemin vers 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. )

Intégrer Flask et APIspec

1. Installez Flask et Flask-Apispec

pip install Flask Flask-Apispec

2. Créez une application 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()

Intégrer Django et APIspec

1. Installez Django et Django-Rest-Framework

pip install django djangorestframework

2. Créer des projets et des applications Django

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

3. Configurer le projet Django

Ajoutez rest_framework et apispec dans settings.py :

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

4. Définir les vues Django

Dans monapp/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. Configurer l'URL

Dans monapp/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. Générer la spécification OpenAPI

Dans gérer.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())

03Fonctionnalités avancées d'APIspec

1. Générateur personnalisé

APIspec fournit un mécanisme d'extension flexible qui vous permet de personnaliser les générateurs. Vous pouvez implémenter votre propre logique de génération en héritant et en étendant la classe de base fournie par 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. Prise en charge de plusieurs frameworks

Apispec prend en charge une variété de frameworks Python populaires, tels que Flask, Django, Falcon, etc. Vous pouvez choisir les frameworks et plug-ins appropriés en fonction de vos besoins pour générer rapidement des documents API.

3. Générez automatiquement les documents d'interface

Apispec peut générer automatiquement des documents d'interface basés sur la chaîne de documentation d'une fonction ou d'une classe, réduisant ainsi la charge de travail liée à l'écriture manuelle de documents.

  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. Intégrez des outils tiers

Apispec peut être intégré à de nombreux outils tiers, tels que Swagger UI, ReDoc, etc., pour fournir des fonctions intuitives d'affichage et de test des documents d'interface.

  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()

04Cas pratiques

Construire un système de documentation API complet

1. Présentation du projet

Supposons que nous ayons un système de gestion des utilisateurs simple et que nous devions documenter son API. Notre API comprend des opérations d'ajout, de suppression, de modification et de requête d'utilisateurs, ainsi que certaines fonctions de base d'authentification d'identité.

2. Structure du projet

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

3. Installer les dépendances

Ajoutez des dépendances dans Requirements.txt :

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

Exécutez la commande suivante pour installer les dépendances :

pip install -r requirements.txt

4. Définir le modèle

Définissez le modèle utilisateur dans 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. Définir les vues et la sérialisation

Définissez les sérialiseurs utilisateur dans 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.

Définir des vues dans vues.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. Définir l'application principale

Dans 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. Exécutez l'application et consultez la documentation

Démarrez l'application en exécutant la commande suivante :

python app.py

Visitez http://localhost:5000/swagger/ pour afficher la documentation de l'API générée.

05Les meilleures pratiques

1. Gardez la documentation et le code synchronisés

Assurez-vous que la documentation est toujours synchronisée avec le code pour éviter les incohérences entre la documentation et l'API réelle. Vous pouvez utiliser les outils CI/CD pour générer et déployer automatiquement la documentation.

2. Utilisez des annotations et des décorateurs

En utilisant des annotations et des décorateurs, la documentation peut être rendue plus concise et lisible. Par exemple, utilisez le décorateur @doc de Flask-Apispec pour ajouter des informations de documentation à une fonction d'affichage.

3. Définir les paramètres et les réponses globaux

Pour les paramètres et réponses couramment utilisés, des paramètres globaux et des modèles de réponse peuvent être définis dans Apispec afin de réduire le code répété.

  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. Examiner et mettre à jour régulièrement la documentation

Examiner et mettre à jour régulièrement la documentation pour garantir son exactitude et son exhaustivité. Ceci peut être réalisé en mettant en place un cycle d’examen des documents ou en introduisant un processus d’examen des documents.

Pour plus de fonctions et une utilisation détaillée, veuillez vous référer à la documentation officielle :

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

06résumé

Grâce à cet article, je pense que vous avez une compréhension et une maîtrise de base d'Apispec. De l'utilisation de base aux fonctions avancées, en passant par les cas pratiques et les meilleures pratiques, nous présentons en détail comment utiliser Apispec pour générer et maintenir des documents API.

J'espère que vous pourrez appliquer ces connaissances à des projets réels et ajouter une touche de luminosité à votre API.

Profil personnel

Il se consacre à la recherche technologique depuis plus de 30 ans et maîtrise divers langages tels que java, linux, javascript, php, css, etc. Il a apporté de nombreuses contributions dans le domaine de l'open source. station de documentation pour les développeurs pour partager certains problèmes de développement technologique pour référence future.

mes coordonnées

Mail