Technology sharing

Apispec, bibliotheca Pythonis OpenAPI generandi (Swagger) specifications

2024-07-12

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

Tabula contentorum

01What est APIspec?

Cur Apispec eligere?

Installation et configuratione

02Basic usus Apispec

Generare simplex API documenta

1. crea in Apispec exempli gratia

2. Definire API itineribus ac views

3. Add iter ad Apispec

Integrate Vas et APIspec

1. Install Flask et Flask-Apispec

2. crea in application utrem

Integrate Django et APIspec

1. Install Django et Django-Requiem-Framework

2. crea Django incepta et applicationes

3. Configure Django project

4. Define Django views

5. Configure URL

6. OpenAPI generale speciem

03Apispec provectis

1. Custom generantis

2. Support plures compages

3. Automatarie generate documentorum interface

4. Integrate cum tertia-pars instrumenta

04Practical casibus

1. Project Introduction

2. Project structure

3. Install clientelas

4. Definire exemplum

5. Definire views ac serialization

6. Definire pelagus application

7. Curre in app ac videre documenta

Visita http://localhost:5000/swagger/ videre generatum API documentum.

05Best Practices

06 Summarium


01Quid est APIspec?

Introductio ad APIspecs

Apispec bibliotheca Python est OpenAPI (Swagger) species generandi. Potest auxilium tincidunt automatice API documenta generare et conservare et descriptiones intuitivas et distinctissimas instrumenti praebere. Per Apispec documenta chorda Pythonis functionis vel classis facile convertere possumus in documentum quod specificationi OpenAPI congruit, molestiam manualem scriptionis documentorum minuens.

Cur Apispec eligere?

  • Simplex et facilis ad usum: Apispec API simplex et facile utendum praebet ut cito incipias.

  • Flexibile et potentem: Sustinet plures compages (ut Flask, Django) et extensiones, permittens te generationi documenti customize ut opus sit.

  • automation: Operationes manuales et sustentationem minuere sumptibus automatice documentis generandis et adaequationis.

Installation et configuratione

Priusquam incipimus uti Apispec, necesse est ut eam prius instituam. Potes eam uti pituitam instituere:

pip install apispec

Github project inscriptio:

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

02Basic usus APIspec

Intueamur usum fundamentalem Apispec per pauca simplicia exempla.

Generare simplex API documenta

1. crea in Apispec exempli gratia

  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 API itineribus ac views

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

Integrate Vas et APIspec

1. Install Flask et Flask-Apispec

pip install Flask Flask-Apispec

2. crea in application utrem

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

Integrate Django et APIspec

1. Install Django et Django-Requiem-Framework

pip install django djangorestframework

2. crea Django incepta et applicationes

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

3. Configure Django project

Add rest_framework et apispec in settings.py:

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

4. Define Django views

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. Configure 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. OpenAPI generale speciem

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

03Provectus lineamenta APIspec

1. Custom generantis

APIspec extensio mechanismum flexibilem praebet quae te generantibus domiciliis concedit. Potes efficere logicam suam generationem tuam possidendo et ampliando genus basis ab Apispec provisum.

  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. Support plures compages

Apispec varias tabulas Pythonis populares sustinet, ut Flask, Django, Falcon, etc. Potes aptas tabulas eligere et obturaculum secundum necessitates tuas ut documenta API cito gignant.

3. Automatarie generate documentorum interface

Apispec statim generare potest documenta interfaciei innixa in chorda documenti functionis vel classis, reducendo inposuit quod inposuit documentorum manualium scripto.

  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. Integrate cum tertia-pars instrumenta

Apispec integrari potest cum multis instrumentis tertiae factionis, ut Swagger UI, ReDoc, etc., ut documentum intuitivum instrumenti interfaciei praebeat et functiones experiatur.

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

04Causae practicae

Aedificare completum API documentis ratio

1. Project Introduction

Ponamus nos simplicem usoris administratione rationem habere et opus API eius documento habere. Nostra API user additionem, deletionem, modificationem et interrogationes operationes includit, ac quaedam functiones authenticas fundamentales identitatis.

2. Project structure

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

3. Install clientelas

Adde clientelas in requirements.txt:

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

Hoc mandatum est curre clientelas install:

pip install -r requirements.txt

4. Definire exemplum

Define usoris exemplar 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 views ac serialization

Define user serializers 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.

Define views 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 pelagus application

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. Curre in app ac videre documenta

Incipit per applicationem currit hoc mandatum:

python app.py

Visita http://localhost:5000/swagger/ videre generatum API documentum.

05Optimus exercitia

1. Documenta custodi et code in sync

Curare documenta semper in sync cum codice ad vitandas repugnantias inter documenta et ipsam API. CI/CD instrumenta uti potes ad documenta sponte generanda et explicanda.

2. Annotationibus et ornamentis utere

Adhibitis annotationibus et ornamentis, documentum brevius et lectabile fieri potest. Exempli gratia, usus est ornamento Flask-Apispec @doc ornatum ad informationes documentorum ad visum munus addere.

3. Definire global parametri et respondeo

Pro parametris et responsionibus communiter adhibitis, parametri globalis et solutionum responsionum definiri possunt in Apispec ad iterandum codicem reducendum.

  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. Regulariter review ac update documenta

Regulariter recensere et renovare documenta ut accurationem et perfectionem curent. Quod fieri potest ut instituatur documentum cycli recensionis vel documentum processus retractationis introducendo.

Ad plura munera et accuratiores usus, ad documenta publica referre placet;

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

06summarium

Per hunc articulum, credo, te Apispec praecipuum intellectum et magisterium habere. Ex usu fundamentali ad functiones provectas, ad causas practicas et ad optimos usus, comprehendimus comprehendimus quomodo Apispec utatur ad documenta generanda et conservanda API.

Spero te hanc scientiam ad incepta actualia applicare et tactum claritatis tuis API addere.

Personal profile

technologiae technologiae plus quam 30 annos operam dedit et in variis linguis proficit ut java, linux, javascript, php, css, etc. Multas contributiones in aperto fonte campo fecit elit documentorum statione ad communicandas quaestiones in technologia progressus ad futuram referentiam.

mihi contactus notitia

Mail