Condivisione della tecnologia

Apispec, una libreria Python per generare specifiche OpenAPI (Swagger).

2024-07-12

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

Sommario

01Che cos'è la specifica API?

Perché scegliere Apispec?

Installazione e configurazione

02Utilizzo base di Apispec

Genera semplice documentazione API

1. Crea un'istanza Apispec

2. Definire percorsi e visualizzazioni API

3. Aggiungi il percorso ad Apispec

Integra Flask e APIspec

1. Installare Flask e Flask-Apispec

2. Creare un'applicazione Flask

Integra Django e APIspec

1. Installa Django e Django-Rest-Framework

2. Crea progetti e applicazioni Django

3. Configura il progetto Django

4. Definire le visualizzazioni Django

5. Configura l'URL

6. Genera la specifica OpenAPI

Le funzionalità avanzate di 03Apispec

1. Generatore personalizzato

2. Supporta più framework

3. Genera automaticamente documenti di interfaccia

4. Integrazione con strumenti di terze parti

04Casi pratici

1. Introduzione al progetto

2. Struttura del progetto

3. Installa le dipendenze

4. Definire il modello

5. Definire visualizzazioni e serializzazione

6. Definire l'applicazione principale

7. Eseguire l'app e visualizzare la documentazione

Visita http://localhost:5000/swagger/ per visualizzare la documentazione dell'API generata.

05Migliori pratiche

06 Riepilogo


01Cos'è la specifica API?

Introduzione alle specifiche API

Apispec è una libreria Python per generare specifiche OpenAPI (Swagger). Può aiutare gli sviluppatori a generare e gestire automaticamente i documenti API e fornire descrizioni dell'interfaccia intuitive e dettagliate. Attraverso Apispec, possiamo convertire facilmente la stringa di documentazione di una funzione o classe Python in un documento conforme alle specifiche OpenAPI, riducendo il problema di scrivere manualmente la documentazione.

Perché scegliere Apispec?

  • Semplice e facile da usare: Apispec fornisce un'API semplice e facile da usare per iniziare rapidamente.

  • Flessibile e potente: supporta più framework (come Flask, Django) ed estensioni, consentendo di personalizzare la generazione di documenti in base alle esigenze.

  • automazione: Riduci le operazioni manuali e i costi di manutenzione generando e aggiornando automaticamente i documenti.

Installazione e configurazione

Prima di iniziare a utilizzare Apispec, dobbiamo prima installarlo. Puoi installarlo usando pip:

pip install apispec

Indirizzo del progetto Github:

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

02Utilizzo di base di APIspec

Diamo un'occhiata all'utilizzo di base di Apispec attraverso alcuni semplici esempi.

Genera semplice documentazione API

1. Crea un'istanza 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. Definire percorsi e visualizzazioni 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. Aggiungi il percorso ad 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. )

Integra Flask e APIspec

1. Installare Flask e Flask-Apispec

pip install Flask Flask-Apispec

2. Creare un'applicazione 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 e APIspec

1. Installa Django e Django-Rest-Framework

pip install django djangorestframework

2. Crea progetti e applicazioni Django

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

3. Configura il progetto Django

Aggiungi rest_framework e apispec in settings.py:

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

4. Definire le visualizzazioni Django

In 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. Configura l'URL

In 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. Genera la specifica OpenAPI

In Manage.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())

03Funzionalità avanzate di APIspec

1. Generatore personalizzato

APIspec fornisce un meccanismo di estensione flessibile che consente di personalizzare i generatori. Puoi implementare la tua logica di generazione ereditando ed estendendo la classe base fornita da 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. Supporta più framework

Apispec supporta una varietà di framework Python popolari, come Flask, Django, Falcon, ecc. Puoi scegliere framework e plug-in appropriati in base alle tue esigenze e generare rapidamente documenti API.

3. Genera automaticamente documenti di interfaccia

Apispec può generare automaticamente documenti di interfaccia basati sulla stringa di documentazione di una funzione o classe, riducendo il carico di lavoro della scrittura manuale dei documenti.

  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. Integrazione con strumenti di terze parti

Apispec può essere integrato con molti strumenti di terze parti, come Swagger UI, ReDoc, ecc., per fornire funzioni di visualizzazione e test dei documenti con interfaccia 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()

04Casi pratici

Costruisci un sistema di documentazione API completo

1. Introduzione al progetto

Supponiamo di avere un semplice sistema di gestione degli utenti e di dover documentare la sua API. La nostra API include operazioni di aggiunta, eliminazione, modifica e query degli utenti, nonché alcune funzioni di base di autenticazione dell'identità.

2. Struttura del progetto

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

3. Installa le dipendenze

Aggiungi le dipendenze in require.txt:

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

Eseguire il comando seguente per installare le dipendenze:

pip install -r requirements.txt

4. Definire il modello

Definisci il modello utente in 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. Definire visualizzazioni e serializzazione

Definisci i serializzatori utente in 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.

Definisci le visualizzazioni in 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. Definire l'applicazione principale

In 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. Eseguire l'app e visualizzare la documentazione

Avviare l'applicazione eseguendo il comando seguente:

python app.py

Visita http://localhost:5000/swagger/ per visualizzare la documentazione dell'API generata.

05Migliori pratiche

1. Mantieni la documentazione e il codice sincronizzati

Assicurati che la documentazione sia sempre sincronizzata con il codice per evitare incoerenze tra la documentazione e l'API effettiva. È possibile utilizzare gli strumenti CI/CD per generare e distribuire automaticamente la documentazione.

2. Utilizzare annotazioni e decoratori

Utilizzando commenti e decoratori, la documentazione può essere resa più concisa e leggibile. Ad esempio, utilizza il decoratore @doc di Flask-Apispec per aggiungere informazioni sulla documentazione a una funzione di visualizzazione.

3. Definire parametri e risposte globali

Per i parametri e le risposte di uso comune, è possibile definire parametri globali e modelli di risposta in Apispec per ridurre la ripetizione del codice.

  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. Rivedere e aggiornare regolarmente la documentazione

Rivedere e aggiornare regolarmente la documentazione per garantirne l'accuratezza e la completezza. Ciò può essere ottenuto impostando un ciclo di revisione dei documenti o introducendo un processo di revisione dei documenti.

Per ulteriori funzioni e utilizzo dettagliato, fare riferimento alla documentazione ufficiale:

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

06riepilogo

Attraverso questo articolo, credo che tu abbia una conoscenza e una padronanza di base di Apispec. Dall'utilizzo di base alle funzioni avanzate, ai casi pratici e alle migliori pratiche, presentiamo in modo completo come utilizzare Apispec per generare e mantenere documenti API.

Spero che tu possa applicare questa conoscenza a progetti reali e aggiungere un tocco di luminosità alla tua API.

Profilo personale

Si dedica alla ricerca tecnologica da più di 30 anni ed è esperto in vari linguaggi come Java, Linux, Javascript, php, css, ecc. Ha dato numerosi contributi nel campo dell'open source stazione di documentazione per gli sviluppatori per condividere alcuni problemi nello sviluppo della tecnologia per riferimento futuro

le mie informazioni di contatto

Posta