Technologieaustausch

Apispec, eine Python-Bibliothek zum Generieren von OpenAPI-Spezifikationen (Swagger).

2024-07-12

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

Inhaltsverzeichnis

01Was ist APIspec?

Warum Apispec wählen?

Installation und Konfiguration

02Grundlegende Verwendung von Apispec

Generieren Sie eine einfache API-Dokumentation

1. Erstellen Sie eine Apispec-Instanz

2. Definieren Sie API-Routen und -Ansichten

3. Pfad zu Apispec hinzufügen

Integrieren Sie Flask und APIspec

1. Installieren Sie Flask und Flask-Apispec

2. Erstellen Sie eine Flask-Anwendung

Integrieren Sie Django und APIspec

1. Installieren Sie Django und Django-Rest-Framework

2. Erstellen Sie Django-Projekte und -Anwendungen

3. Konfigurieren Sie das Django-Projekt

4. Definieren Sie Django-Ansichten

5. URL konfigurieren

6. Generieren Sie die OpenAPI-Spezifikation

03Apispecs erweiterte Funktionen

1. Benutzerdefinierter Generator

2. Unterstützen Sie mehrere Frameworks

3. Schnittstellendokumente automatisch generieren

4. Integration mit Tools von Drittanbietern

04Praxisfälle

1. Projekteinführung

2. Projektstruktur

3. Abhängigkeiten installieren

4. Definieren Sie das Modell

5. Definieren Sie Ansichten und Serialisierung

6. Definieren Sie die Hauptanwendung

7. Führen Sie die App aus und sehen Sie sich die Dokumentation an

Besuchen Sie http://localhost:5000/swagger/, um die generierte API-Dokumentation anzuzeigen.

05Best Practices

06 Zusammenfassung


01Was ist APIspec?

Einführung in APIspecs

Apispec ist eine Python-Bibliothek zum Generieren von OpenAPI-Spezifikationen (Swagger). Es kann Entwicklern helfen, API-Dokumente automatisch zu erstellen und zu verwalten und intuitive und detaillierte Schnittstellenbeschreibungen bereitzustellen. Mit Apispec können wir die Dokumentationszeichenfolge einer Python-Funktion oder -Klasse problemlos in ein Dokument konvertieren, das der OpenAPI-Spezifikation entspricht, wodurch der Aufwand beim manuellen Schreiben der Dokumentation verringert wird.

Warum Apispec wählen?

  • Einfach und leicht zu bedienen: Apispec bietet eine einfache und benutzerfreundliche API, die Ihnen einen schnellen Einstieg ermöglicht.

  • Flexibel und leistungsstark: Unterstützt mehrere Frameworks (wie Flask, Django) und Erweiterungen, sodass Sie die Dokumenterstellung nach Bedarf anpassen können.

  • Automatisierung: Reduzieren Sie manuelle Vorgänge und Wartungskosten durch die automatische Generierung und Aktualisierung von Dokumenten.

Installation und Konfiguration

Bevor wir Apispec verwenden können, müssen wir es zunächst installieren. Sie können es mit pip installieren:

pip install apispec

Github-Projektadresse:

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

02Grundlegende Verwendung von APIspec

Schauen wir uns die grundlegende Verwendung von Apispec anhand einiger einfacher Beispiele an.

Generieren Sie eine einfache API-Dokumentation

1. Erstellen Sie eine Apispec-Instanz

  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. Definieren Sie API-Routen und -Ansichten

  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. Pfad zu Apispec hinzufügen

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

Integrieren Sie Flask und APIspec

1. Installieren Sie Flask und Flask-Apispec

pip install Flask Flask-Apispec

2. Erstellen Sie eine Flask-Anwendung

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

Integrieren Sie Django und APIspec

1. Installieren Sie Django und Django-Rest-Framework

pip install django djangorestframework

2. Erstellen Sie Django-Projekte und -Anwendungen

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

3. Konfigurieren Sie das Django-Projekt

Fügen Sie rest_framework und apispec in Settings.py hinzu:

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

4. Definieren Sie Django-Ansichten

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. URL konfigurieren

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. Generieren Sie die OpenAPI-Spezifikation

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

03Erweiterte Funktionen von APIspec

1. Benutzerdefinierter Generator

APIspec bietet einen flexiblen Erweiterungsmechanismus, mit dem Sie Generatoren anpassen können. Sie können Ihre eigene Generierungslogik implementieren, indem Sie die von Apispec bereitgestellte Basisklasse erben und erweitern.

  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. Unterstützen Sie mehrere Frameworks

Apispec unterstützt eine Vielzahl beliebter Python-Frameworks wie Flask, Django, Falcon usw. Sie können je nach Bedarf geeignete Frameworks und Plug-Ins auswählen, um schnell API-Dokumente zu generieren.

3. Schnittstellendokumente automatisch generieren

Apispec kann automatisch Schnittstellendokumente basierend auf der Dokumentationszeichenfolge einer Funktion oder Klasse generieren und so den Arbeitsaufwand für das manuelle Schreiben von Dokumenten reduzieren.

  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. Integration mit Tools von Drittanbietern

Apispec kann in viele Tools von Drittanbietern wie Swagger UI, ReDoc usw. integriert werden, um intuitive Schnittstellendokumentanzeige- und Testfunktionen bereitzustellen.

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

04Praktische Fälle

Erstellen Sie ein vollständiges API-Dokumentationssystem

1. Projekteinführung

Angenommen, wir haben ein einfaches Benutzerverwaltungssystem und müssen dessen API dokumentieren. Unsere API umfasst Vorgänge zum Hinzufügen, Löschen, Ändern und Abfragen von Benutzern sowie einige grundlegende Funktionen zur Identitätsauthentifizierung.

2. Projektstruktur

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

3. Abhängigkeiten installieren

Fügen Sie Abhängigkeiten in „requirements.txt“ hinzu:

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

Führen Sie den folgenden Befehl aus, um Abhängigkeiten zu installieren:

pip install -r requirements.txt

4. Definieren Sie das Modell

Definieren Sie das Benutzermodell 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. Definieren Sie Ansichten und Serialisierung

Definieren Sie Benutzerserialisierer 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.

Definieren Sie Ansichten 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. Definieren Sie die Hauptanwendung

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. Führen Sie die App aus und sehen Sie sich die Dokumentation an

Starten Sie die Anwendung, indem Sie den folgenden Befehl ausführen:

python app.py

Besuchen Sie http://localhost:5000/swagger/, um die generierte API-Dokumentation anzuzeigen.

05Empfohlene Vorgehensweise

1. Halten Sie Dokumentation und Code synchron

Stellen Sie sicher, dass die Dokumentation immer mit dem Code synchronisiert ist, um Inkonsistenzen zwischen der Dokumentation und der tatsächlichen API zu vermeiden. Sie können CI/CD-Tools verwenden, um Dokumentation automatisch zu generieren und bereitzustellen.

2. Verwenden Sie Anmerkungen und Dekoratoren

Durch die Verwendung von Kommentaren und Dekoratoren kann die Dokumentation prägnanter und lesbarer gestaltet werden. Verwenden Sie beispielsweise den @doc-Dekorator von Flask-Apispec, um Dokumentationsinformationen zu einer Ansichtsfunktion hinzuzufügen.

3. Definieren Sie globale Parameter und Reaktionen

Für häufig verwendete Parameter und Antworten können in Apispec globale Parameter und Antwortvorlagen definiert werden, um wiederholten Code zu reduzieren.

  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. Überprüfen und aktualisieren Sie die Dokumentation regelmäßig

Überprüfen und aktualisieren Sie die Dokumentation regelmäßig, um Richtigkeit und Vollständigkeit sicherzustellen. Dies kann durch die Einrichtung eines Dokumentenüberprüfungszyklus oder die Einführung eines Dokumentenüberprüfungsprozesses erreicht werden.

Weitere Funktionen und eine detaillierte Verwendung finden Sie in der offiziellen Dokumentation:

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

06Zusammenfassung

Ich glaube, dass Sie durch diesen Artikel ein grundlegendes Verständnis und eine Beherrschung von Apispec erworben haben. Von der grundlegenden Verwendung über erweiterte Funktionen bis hin zu praktischen Fällen und Best Practices stellen wir umfassend vor, wie Sie Apispec zum Generieren und Verwalten von API-Dokumenten verwenden.

Ich hoffe, dass Sie dieses Wissen auf tatsächliche Projekte anwenden und Ihrer API einen Hauch von Helligkeit verleihen können.

Persönliches Profil

Er widmet sich seit mehr als 30 Jahren der Technologieforschung und beherrscht verschiedene Sprachen wie Java, Linux, Javascript, PHP, CSS usw. Er hat viele Beiträge im Open-Source-Bereich geleistet, Entwicklerdokumentationsstation, um einige Themen in der Technologieentwicklung als zukünftige Referenz zu teilen

meine Kontaktdaten

Post