Обмен технологиями

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.

03Расширенные функции Apispec

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.

В файле 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())

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. Установите зависимости

Добавьте зависимости в файл require.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. Определите представления и сериализацию

Определите пользовательские сериализаторы в сериализаторах.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.

Определите представления в view.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 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 и т. д. Он внес большой вклад в область открытого исходного кода. Станция документации для разработчиков, где можно поделиться некоторыми проблемами в разработке технологий для дальнейшего использования. Все ознакомьтесь.

моя контактная информация

Почта