Κοινή χρήση τεχνολογίας

Apispec, μια βιβλιοθήκη Python για τη δημιουργία προδιαγραφών OpenAPI (Swagger).

2024-07-12

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

Πίνακας περιεχομένων

01 Τι είναι το APIspec;

Γιατί να επιλέξετε το Apispec;

Εγκατάσταση και διαμόρφωση

02Βασική χρήση του Apispec

Δημιουργήστε απλή τεκμηρίωση API

1. Δημιουργήστε μια παρουσία Apispec

2. Καθορίστε διαδρομές και προβολές API

3. Προσθέστε διαδρομή στο Apispec

Ενσωματώστε το Flask και το APIspec

1. Εγκαταστήστε το Flask και το Flask-Apispec

2. Δημιουργήστε μια εφαρμογή Flask

Ενσωματώστε το Django και το APIspec

1. Εγκαταστήστε το Django και το Django-Rest-Framework

2. Δημιουργήστε έργα και εφαρμογές Django

3. Διαμόρφωση έργου Django

4. Ορίστε τις προβολές Django

5. Διαμόρφωση διεύθυνσης URL

6. Δημιουργήστε προδιαγραφές OpenAPI

Προηγμένες δυνατότητες του 03Apispec

1. Προσαρμοσμένη γεννήτρια

2. Υποστήριξη πολλαπλών πλαισίων

3. Αυτόματη δημιουργία εγγράφων διεπαφής

4. Ενσωματωθείτε με εργαλεία τρίτων

04Πρακτικές περιπτώσεις

1. Εισαγωγή Έργου

2. Δομή έργου

3. Εγκαταστήστε εξαρτήσεις

4. Καθορίστε το μοντέλο

5. Ορίστε προβολές και σειριοποίηση

6. Καθορίστε την κύρια εφαρμογή

7. Εκτελέστε την εφαρμογή και προβάλετε την τεκμηρίωση

Επισκεφτείτε τη διεύθυνση http://localhost:5000/swagger/ για να προβάλετε την τεκμηρίωση του API που δημιουργήθηκε.

05 Βέλτιστες πρακτικές

06 Περίληψη


01Τι είναι το APIspec;

Εισαγωγή στις προδιαγραφές API

Το Apispec είναι μια βιβλιοθήκη Python για τη δημιουργία προδιαγραφών OpenAPI (Swagger). Μπορεί να βοηθήσει τους προγραμματιστές να δημιουργούν και να διατηρούν αυτόματα έγγραφα API και να παρέχουν εύχρηστες και λεπτομερείς περιγραφές διεπαφής. Μέσω του Apispec, μπορούμε εύκολα να μετατρέψουμε τη συμβολοσειρά τεκμηρίωσης μιας συνάρτησης ή κλάσης Python σε έγγραφο που συμμορφώνεται με την προδιαγραφή OpenAPI, μειώνοντας το πρόβλημα της μη αυτόματης εγγραφής τεκμηρίωσης.

Γιατί να επιλέξετε το Apispec;

  • Απλό και εύκολο στη χρήση: Το Apispec παρέχει ένα απλό και εύχρηστο API, ώστε να μπορείτε να ξεκινήσετε γρήγορα.

  • Ευέλικτο και δυνατό: Υποστηρίζει πολλαπλά πλαίσια (όπως Flask, Django) και επεκτάσεις, επιτρέποντάς σας να προσαρμόσετε τη δημιουργία εγγράφων όπως απαιτείται.

  • αυτοματοποίηση: Μειώστε τις χειροκίνητες λειτουργίες και το κόστος συντήρησης με την αυτόματη δημιουργία και ενημέρωση εγγράφων.

Εγκατάσταση και διαμόρφωση

Πριν αρχίσουμε να χρησιμοποιούμε το Apispec, πρέπει πρώτα να το εγκαταστήσουμε. Μπορείτε να το εγκαταστήσετε χρησιμοποιώντας το pip:

pip install apispec

Διεύθυνση έργου Github:

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

02Βασική χρήση του APIspec

Ας δούμε τη βασική χρήση του Apispec μέσα από μερικά απλά παραδείγματα.

Δημιουργήστε απλή τεκμηρίωση API

1. Δημιουργήστε μια παρουσία 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. Καθορίστε διαδρομές και προβολές 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. Προσθέστε διαδρομή στο 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. )

Ενσωματώστε το Flask και το APIspec

1. Εγκαταστήστε το Flask και το Flask-Apispec

pip install Flask Flask-Apispec

2. Δημιουργήστε μια εφαρμογή 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()

Ενσωματώστε το Django και το APIspec

1. Εγκαταστήστε το Django και το Django-Rest-Framework

pip install django djangorestframework

2. Δημιουργήστε έργα και εφαρμογές Django

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

3. Διαμόρφωση έργου Django

Προσθέστε rest_framework και apispec στο settings.py:

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

4. Ορίστε τις προβολές Django

Στο 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

Στο 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. Δημιουργήστε προδιαγραφές OpenAPI

Στο manager.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())

03Προηγμένες δυνατότητες του APIspec

1. Προσαρμοσμένη γεννήτρια

Το APIspec παρέχει έναν ευέλικτο μηχανισμό επέκτασης που σας επιτρέπει να προσαρμόσετε τις γεννήτριες. Μπορείτε να εφαρμόσετε τη δική σας λογική γενιάς κληρονομώντας και επεκτείνοντας τη βασική κλάση που παρέχεται από την 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. Υποστήριξη πολλαπλών πλαισίων

Το Apispec υποστηρίζει μια ποικιλία από δημοφιλή πλαίσια Python, όπως Flask, Django, Falcon κ.λπ. Μπορείτε να επιλέξετε κατάλληλα πλαίσια και πρόσθετα ανάλογα με τις ανάγκες σας και να δημιουργήσετε γρήγορα έγγραφα API.

3. Αυτόματη δημιουργία εγγράφων διεπαφής

Το Apispec μπορεί να δημιουργήσει αυτόματα έγγραφα διεπαφής με βάση τη συμβολοσειρά τεκμηρίωσης μιας συνάρτησης ή μιας κλάσης, μειώνοντας τον φόρτο εργασίας της μη αυτόματης εγγραφής εγγράφων.

  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. Ενσωματωθείτε με εργαλεία τρίτων

Το Apispec μπορεί να ενσωματωθεί με πολλά εργαλεία τρίτων, όπως το Swagger UI, το ReDoc, κ.λπ., για να παρέχει εύχρηστες λειτουργίες προβολής εγγράφων διεπαφής και δοκιμών.

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

04Πρακτικές περιπτώσεις

Δημιουργήστε ένα πλήρες σύστημα τεκμηρίωσης API

1. Εισαγωγή Έργου

Ας υποθέσουμε ότι έχουμε ένα απλό σύστημα διαχείρισης χρηστών και πρέπει να τεκμηριώσουμε το API του. Το API μας περιλαμβάνει λειτουργίες προσθήκης, διαγραφής, τροποποίησης και ερωτήματος χρήστη, καθώς και ορισμένες βασικές λειτουργίες ελέγχου ταυτότητας.

2. Δομή έργου

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

3. Εγκαταστήστε εξαρτήσεις

Προσθήκη εξαρτήσεων στο request.txt:

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

Εκτελέστε την ακόλουθη εντολή για να εγκαταστήσετε εξαρτήσεις:

pip install -r requirements.txt

4. Καθορίστε το μοντέλο

Ορίστε το μοντέλο χρήστη στο 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. Ορίστε προβολές και σειριοποίηση

Ορίστε τους σειριακούς χρήστες στο 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.

Ορισμός προβολών στο 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. Καθορίστε την κύρια εφαρμογή

Στο 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. Εκτελέστε την εφαρμογή και προβάλετε την τεκμηρίωση

Ξεκινήστε την εφαρμογή εκτελώντας την ακόλουθη εντολή:

python app.py

Επισκεφτείτε τη διεύθυνση http://localhost:5000/swagger/ για να προβάλετε την τεκμηρίωση του API που δημιουργήθηκε.

05Βέλτιστες πρακτικές

1. Διατηρήστε την τεκμηρίωση και τον κώδικα σε συγχρονισμό

Βεβαιωθείτε ότι η τεκμηρίωση είναι πάντα σε συγχρονισμό με τον κώδικα για να αποφύγετε ασυνέπειες μεταξύ της τεκμηρίωσης και του πραγματικού API. Μπορείτε να χρησιμοποιήσετε εργαλεία CI/CD για αυτόματη δημιουργία και ανάπτυξη τεκμηρίωσης.

2. Χρησιμοποιήστε σχολιασμούς και διακοσμητές

Χρησιμοποιώντας σχόλια και διακοσμητές, η τεκμηρίωση μπορεί να γίνει πιο συνοπτική και ευανάγνωστη. Για παράδειγμα, χρησιμοποιήστε το @doc decorator του Flask-Apispec για να προσθέσετε πληροφορίες τεκμηρίωσης σε μια λειτουργία προβολής.

3. Ορίστε καθολικές παραμέτρους και αποκρίσεις

Για παραμέτρους και αποκρίσεις που χρησιμοποιούνται συνήθως, καθολικές παράμετροι και πρότυπα απόκρισης μπορούν να οριστούν στο Apispec για μείωση του επαναλαμβανόμενου κώδικα.

  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. Επανεξετάζετε και ενημερώνετε τακτικά την τεκμηρίωση

Ελέγχετε και ενημερώνετε τακτικά την τεκμηρίωση για να διασφαλίζετε την ακρίβεια και την πληρότητα. Αυτό μπορεί να επιτευχθεί με τη δημιουργία ενός κύκλου αναθεώρησης εγγράφων ή με την εισαγωγή μιας διαδικασίας αναθεώρησης εγγράφων.

Για περισσότερες λειτουργίες και λεπτομερή χρήση, ανατρέξτε στην επίσημη τεκμηρίωση:

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

06περίληψη

Μέσα από αυτό το άρθρο, πιστεύω ότι έχετε μια βασική κατανόηση και κυριαρχία του Apispec. Από τη βασική χρήση έως τις προηγμένες λειτουργίες, έως τις πρακτικές περιπτώσεις και τις βέλτιστες πρακτικές, παρουσιάζουμε αναλυτικά τον τρόπο χρήσης του Apispec για τη δημιουργία και τη συντήρηση εγγράφων API.

Ελπίζω να μπορείτε να εφαρμόσετε αυτή τη γνώση σε πραγματικά έργα και να προσθέσετε μια νότα φωτεινότητας στο API σας.

Προσωπικό προφίλ

Έχει αφοσιωθεί στην έρευνα της τεχνολογίας για περισσότερα από 30 χρόνια και είναι ικανός σε διάφορες γλώσσες όπως java, linux, javascript, php, css κ.λπ. Έχει κάνει πολλές συνεισφορές στον τομέα του ανοιχτού κώδικα σταθμός τεκμηρίωσης προγραμματιστή για να μοιραστείτε ορισμένα ζητήματα στην ανάπτυξη τεχνολογίας για μελλοντική αναφορά

τα στοιχεία επικοινωνίας μου

Ταχυδρομείο