Berbagi teknologi

Apispec, perpustakaan Python untuk menghasilkan spesifikasi OpenAPI (Swagger).

2024-07-12

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

Daftar isi

01Apa itu spesifikasi API?

Mengapa memilih Apispec?

Instalasi dan konfigurasi

02Penggunaan dasar Apispec

Hasilkan dokumentasi API sederhana

1. Buat instans Apispec

2. Tentukan rute dan tampilan API

3. Tambahkan jalur ke Apispec

Integrasikan Flask dan APIspec

1. Instal Flask dan Flask-Apispec

2. Buat aplikasi Flask

Integrasikan Django dan APIspec

1. Instal Django dan Django-Rest-Framework

2. Membuat proyek dan aplikasi Django

3. Konfigurasikan proyek Django

4. Definisikan pandangan Django

5. Konfigurasikan URL

6. Hasilkan spesifikasi OpenAPI

03Fitur lanjutan Apispec

1. Generator khusus

2. Mendukung berbagai kerangka kerja

3. Secara otomatis menghasilkan dokumen antarmuka

4. Integrasikan dengan alat pihak ketiga

04Kasus praktis

1. Pengenalan Proyek

2. Struktur proyek

3. Instal dependensi

4. Tentukan modelnya

5. Tentukan tampilan dan serialisasi

6. Tentukan aplikasi utama

7. Jalankan aplikasi dan lihat dokumentasinya

Kunjungi http://localhost:5000/swagger/ untuk melihat dokumentasi API yang dihasilkan.

05Praktik Terbaik

06 Ringkasan


01Apa itu spesifikasi API?

Pengenalan spesifikasi API

Apispec adalah pustaka Python untuk menghasilkan spesifikasi OpenAPI (Swagger). Ini dapat membantu pengembang secara otomatis menghasilkan dan memelihara dokumen API dan memberikan deskripsi antarmuka yang intuitif dan terperinci. Melalui Apispec, kita dapat dengan mudah mengubah string dokumentasi fungsi atau kelas Python menjadi dokumen yang sesuai dengan spesifikasi OpenAPI, sehingga mengurangi kesulitan menulis dokumentasi secara manual.

Mengapa memilih Apispec?

  • Sederhana dan mudah digunakan: Apispec menyediakan API yang sederhana dan mudah digunakan sehingga Anda dapat memulai dengan cepat.

  • Fleksibel dan kuat: Mendukung banyak kerangka kerja (seperti Flask, Django) dan ekstensi, memungkinkan Anda menyesuaikan pembuatan dokumen sesuai kebutuhan.

  • otomatisasi: Mengurangi biaya pengoperasian dan pemeliharaan manual dengan membuat dan memperbarui dokumen secara otomatis.

Instalasi dan konfigurasi

Sebelum kita mulai menggunakan Apispec, kita perlu menginstalnya terlebih dahulu. Anda dapat menginstalnya menggunakan pip:

pip install apispec

Alamat proyek Github:

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

02Penggunaan dasar APIspec

Mari kita lihat penggunaan dasar Apispec melalui beberapa contoh sederhana.

Hasilkan dokumentasi API sederhana

1. Buat instans 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. Tentukan rute dan tampilan 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. Tambahkan jalur ke 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. )

Integrasikan Flask dan APIspec

1. Instal Flask dan Flask-Apispec

pip install Flask Flask-Apispec

2. Buat aplikasi 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()

Integrasikan Django dan APIspec

1. Instal Django dan Django-Rest-Framework

pip install django djangorestframework

2. Membuat proyek dan aplikasi Django

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

3. Konfigurasikan proyek Django

Tambahkan rest_framework dan apispec di settings.py:

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

4. Definisikan pandangan Django

Di 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. Konfigurasikan URL

Di 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. Hasilkan spesifikasi OpenAPI

Di kelola.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())

03Fitur lanjutan dari APIspec

1. Generator khusus

APIspec menyediakan mekanisme ekstensi fleksibel yang memungkinkan Anda menyesuaikan generator. Anda dapat mengimplementasikan logika generasi Anda sendiri dengan mewarisi dan memperluas kelas dasar yang disediakan oleh 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. Mendukung berbagai kerangka kerja

Apispec mendukung berbagai framework Python populer, seperti Flask, Django, Falcon, dll. Anda dapat memilih kerangka kerja dan plug-in yang sesuai dengan kebutuhan Anda dan dengan cepat menghasilkan dokumen API.

3. Secara otomatis menghasilkan dokumen antarmuka

Apispec dapat secara otomatis menghasilkan dokumen antarmuka berdasarkan string dokumentasi suatu fungsi atau kelas, sehingga mengurangi beban kerja penulisan dokumen secara manual.

  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. Integrasikan dengan alat pihak ketiga

Apispec dapat diintegrasikan dengan banyak alat pihak ketiga, seperti Swagger UI, ReDoc, dll., untuk menyediakan tampilan dokumen antarmuka yang intuitif dan fungsi pengujian.

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

04Kasus-kasus praktis

Bangun sistem dokumentasi API yang lengkap

1. Pengenalan Proyek

Misalkan kita memiliki sistem manajemen pengguna yang sederhana dan perlu mendokumentasikan API-nya. API kami mencakup operasi penambahan, penghapusan, modifikasi dan kueri pengguna, serta beberapa fungsi otentikasi identitas dasar.

2. Struktur proyek

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

3. Instal dependensi

Tambahkan dependensi di persyaratan.txt:

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

Jalankan perintah berikut untuk menginstal dependensi:

pip install -r requirements.txt

4. Tentukan modelnya

Tentukan model pengguna di 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. Tentukan tampilan dan serialisasi

Tentukan serializer pengguna di 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.

Tentukan tampilan di 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. Tentukan aplikasi utama

Di 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. Jalankan aplikasi dan lihat dokumentasinya

Mulai aplikasi dengan menjalankan perintah berikut:

python app.py

Kunjungi http://localhost:5000/swagger/ untuk melihat dokumentasi API yang dihasilkan.

05Praktik terbaik

1. Jaga dokumentasi dan kode tetap sinkron

Pastikan dokumentasi selalu sinkron dengan kode untuk menghindari inkonsistensi antara dokumentasi dan API sebenarnya. Anda dapat menggunakan alat CI/CD untuk membuat dan menyebarkan dokumentasi secara otomatis.

2. Gunakan anotasi dan dekorator

Dengan menggunakan komentar dan dekorator, dokumentasi dapat dibuat lebih ringkas dan mudah dibaca. Misalnya, gunakan dekorator @doc Flask-Apispec untuk menambahkan informasi dokumentasi ke fungsi tampilan.

3. Tentukan parameter dan respons global

Untuk parameter dan respons yang umum digunakan, parameter global dan templat respons dapat ditentukan di Apispec untuk mengurangi kode berulang.

  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. Tinjau dan perbarui dokumentasi secara berkala

Tinjau dan perbarui dokumentasi secara berkala untuk memastikan keakuratan dan kelengkapan. Hal ini dapat dicapai dengan menyiapkan siklus peninjauan dokumen atau memperkenalkan proses peninjauan dokumen.

Untuk fungsi lebih lanjut dan penggunaan detail, silakan merujuk ke dokumentasi resmi:

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

06ringkasan

Melalui artikel ini, saya yakin Anda memiliki pemahaman dasar dan penguasaan Apispec. Dari penggunaan dasar hingga fungsi lanjutan, hingga kasus praktis dan praktik terbaik, kami memperkenalkan secara komprehensif cara menggunakan Apispec untuk menghasilkan dan memelihara dokumen API.

Saya harap Anda dapat menerapkan pengetahuan ini pada proyek sebenarnya dan menambahkan sentuhan kecerahan pada API Anda.

Profil pribadi

Ia telah mengabdikan dirinya untuk meneliti teknologi selama lebih dari 30 tahun, dan mahir dalam berbagai bahasa seperti java, linux, javascript, php, css, dll. Ia telah memberikan banyak kontribusi di bidang open source stasiun dokumentasi pengembang untuk berbagi beberapa masalah dalam pengembangan teknologi untuk referensi di masa mendatang. Semua orang memeriksanya

informasi kontak saya

Surat