Teknologian jakaminen

Apispec, Python-kirjasto OpenAPI (Swagger) -määritysten luomiseen

2024-07-12

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

Sisällysluettelo

01 Mikä APIspec on?

Miksi valita Apispec?

Asennus ja konfigurointi

02 Apispecin peruskäyttö

Luo yksinkertainen API-dokumentaatio

1. Luo Apispec-esiintymä

2. Määritä API-reitit ja näkymät

3. Lisää polku Apispeciin

Integroi Flask ja APIspec

1. Asenna Flask ja Flask-Apispec

2. Luo Flask-sovellus

Integroi Django ja APIspec

1. Asenna Django ja Django-Rest-Framework

2. Luo Django-projekteja ja -sovelluksia

3. Määritä Django-projekti

4. Määritä Django-näkymät

5. Määritä URL-osoite

6. Luo OpenAPI-määritys

03Apispecin lisäominaisuudet

1. Mukautettu generaattori

2. Tukee useita kehyksiä

3. Luo automaattisesti käyttöliittymäasiakirjoja

4. Integroi kolmannen osapuolen työkaluihin

04 Käytännön tapaukset

1. Projektin esittely

2. Hankkeen rakenne

3. Asenna riippuvuudet

4. Määrittele malli

5. Määrittele näkymät ja sarjoittaminen

6. Määritä pääsovellus

7. Suorita sovellus ja tarkastele dokumentaatiota

Vieraile osoitteessa http://localhost:5000/swagger/ nähdäksesi luotu API-dokumentaatio.

05 Parhaat käytännöt

06 Yhteenveto


01Mikä on APIspec?

Johdatus API-määrityksiin

Apispec on Python-kirjasto OpenAPI (Swagger) -määritysten luomiseen. Se voi auttaa kehittäjiä luomaan ja ylläpitämään API-asiakirjoja automaattisesti ja tarjoamaan intuitiivisia ja yksityiskohtaisia ​​käyttöliittymäkuvauksia. Apispecin avulla voimme helposti muuntaa Python-funktion tai -luokan dokumentaatiomerkkijonon OpenAPI-spesifikaatioiden mukaiseksi dokumentiksi, mikä vähentää manuaalisen dokumentaation vaivaa.

Miksi valita Apispec?

  • Yksinkertainen ja helppokäyttöinen: Apispec tarjoaa yksinkertaisen ja helppokäyttöisen sovellusliittymän, joten voit aloittaa nopeasti.

  • Joustava ja tehokas: Tukee useita kehyksiä (kuten Flask, Django) ja laajennuksia, joiden avulla voit mukauttaa asiakirjojen luomista tarpeen mukaan.

  • automaatio: Vähennä manuaalisia toimintoja ja ylläpitokustannuksia luomalla ja päivittämällä asiakirjoja automaattisesti.

Asennus ja konfigurointi

Ennen kuin aloitamme Apispecin käytön, meidän on ensin asennettava se. Voit asentaa sen pip:llä:

pip install apispec

Github-projektin osoite:

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

02APIspecin peruskäyttö

Katsotaanpa Apispecin peruskäyttöä muutaman yksinkertaisen esimerkin kautta.

Luo yksinkertainen API-dokumentaatio

1. Luo Apispec-esiintymä

  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. Määritä API-reitit ja näkymät

  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. Lisää polku Apispeciin

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

Integroi Flask ja APIspec

1. Asenna Flask ja Flask-Apispec

pip install Flask Flask-Apispec

2. Luo Flask-sovellus

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

Integroi Django ja APIspec

1. Asenna Django ja Django-Rest-Framework

pip install django djangorestframework

2. Luo Django-projekteja ja -sovelluksia

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

3. Määritä Django-projekti

Lisää rest_framework ja apispec osoitteeseen settings.py:

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

4. Määritä Django-näkymät

Osoitteessa 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. Määritä URL-osoite

Osoitteessa 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. Luo OpenAPI-määritys

Manager.py:ssä:

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

03APIspecin lisäominaisuudet

1. Mukautettu generaattori

APIspec tarjoaa joustavan laajennusmekanismin, jonka avulla voit mukauttaa generaattoreita. Voit toteuttaa oman sukupolvilogiikkasi perimällä ja laajentamalla Apispecin tarjoamaa perusluokkaa.

  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. Tukee useita kehyksiä

Apispec tukee useita suosittuja Python-kehyksiä, kuten Flask, Django, Falcon jne. Voit valita sopivat puitteet ja laajennukset tarpeidesi mukaan ja luoda nopeasti API-asiakirjoja.

3. Luo automaattisesti käyttöliittymäasiakirjoja

Apispec voi luoda automaattisesti käyttöliittymädokumentteja funktion tai luokan dokumentaatiomerkkijonon perusteella, mikä vähentää asiakirjojen manuaalisen kirjoittamisen työmäärää.

  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. Integroi kolmannen osapuolen työkaluihin

Apispec voidaan integroida moniin kolmansien osapuolien työkaluihin, kuten Swagger UI, ReDoc jne., intuitiivisen käyttöliittymän asiakirjojen näyttö- ja testaustoimintojen tarjoamiseksi.

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

04Käytännön tapauksia

Rakenna täydellinen API-dokumentaatiojärjestelmä

1. Projektin esittely

Oletetaan, että meillä on yksinkertainen käyttäjien hallintajärjestelmä ja meidän on dokumentoitava sen API. Sovellusliittymämme sisältää käyttäjien lisäys-, poisto-, muokkaus- ja kyselytoiminnot sekä joitain perustunnistustoimintoja.

2. Hankkeen rakenne

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

3. Asenna riippuvuudet

Lisää riippuvuudetvaatimukset.txt-tiedostoon:

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

Suorita seuraava komento asentaaksesi riippuvuudet:

pip install -r requirements.txt

4. Määrittele malli

Määritä käyttäjämalli mallissa.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. Määrittele näkymät ja sarjoittaminen

Määritä käyttäjien serialisoijat serializers.py:ssä:

  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.

Määritä näkymät view.py:ssä:

  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. Määritä pääsovellus

App.py:ssä:

  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. Suorita sovellus ja tarkastele dokumentaatiota

Käynnistä sovellus suorittamalla seuraava komento:

python app.py

Vieraile osoitteessa http://localhost:5000/swagger/ nähdäksesi luotu API-dokumentaatio.

05Parhaat käytännöt

1. Pidä asiakirjat ja koodi synkronoituna

Varmista, että dokumentaatio on aina synkronoitu koodin kanssa välttääksesi epäjohdonmukaisuudet dokumentaation ja todellisen API:n välillä. Voit käyttää CI/CD-työkaluja dokumenttien automaattiseen luomiseen ja käyttöönottoon.

2. Käytä huomautuksia ja koristeita

Kommentteja ja sisustajia käyttämällä dokumentaatiosta voidaan tehdä tiiviimpää ja luettavampaa. Käytä esimerkiksi Flask-Apispecin @doc-decoratoria dokumentaatiotietojen lisäämiseen näkymätoimintoon.

3. Määritä globaalit parametrit ja vastaukset

Yleisesti käytetyille parametreille ja vastauksille voidaan määrittää yleiset parametrit ja vastausmallit Apispecissä toistuvan koodin vähentämiseksi.

  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. Tarkista ja päivitä dokumentaatio säännöllisesti

Tarkista ja päivitä asiakirjat säännöllisesti tarkkuuden ja täydellisyyden varmistamiseksi. Tämä voidaan saavuttaa perustamalla asiakirjojen tarkistussykli tai ottamalla käyttöön asiakirjojen tarkistusprosessi.

Lisätietoja toiminnoista ja yksityiskohtaisesta käytöstä on virallisessa dokumentaatiossa:

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

06yhteenveto

Tämän artikkelin kautta uskon, että sinulla on perusymmärrys ja hallinta Apispecistä. Peruskäytöstä edistyneisiin toimintoihin, käytännön tapauksiin ja parhaisiin käytäntöihin, esittelemme kattavasti, kuinka Apispeciä käytetään API-asiakirjojen luomiseen ja ylläpitoon.

Toivon, että voit soveltaa tätä tietoa todellisiin projekteihin ja lisätä sovellusliittymääsi kirkkautta.

Henkilökohtainen profiili

Hän on omistautunut teknologian tutkimukselle yli 30 vuoden ajan ja hallitsee useita kieliä, kuten java, linux, javascript, php, css jne. Hän on tehnyt paljon työtä avoimen lähdekoodin alalla Kehittäjän dokumentaatioasema jakaaksesi joitain teknologian kehityksen ongelmia tulevaa käyttöä varten

yhteystietoni

Mail