기술나눔

OpenAPI(Swagger) 사양을 생성하기 위한 Python 라이브러리인 Apispec

2024-07-12

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

목차

01APIspec이란 무엇인가요?

Apispec을 선택하는 이유는 무엇입니까?

설치 및 구성

02Apispec의 기본 사용법

간단한 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. 앱을 실행하고 설명서를 확인하세요

생성된 API 문서를 보려면 http://localhost:5000/swagger/를 방문하세요.

05모범 사례

06 요약


01APIspec이란 무엇입니까?

API사양 소개

Apispec은 OpenAPI(Swagger) 사양을 생성하기 위한 Python 라이브러리입니다. 개발자가 API 문서를 자동으로 생성 및 유지 관리하고 직관적이고 자세한 인터페이스 설명을 제공하는 데 도움이 될 수 있습니다. Apispec을 통해 Python 함수 또는 클래스의 문서 문자열을 OpenAPI 사양을 준수하는 문서로 쉽게 변환하여 수동으로 문서를 작성하는 수고를 줄일 수 있습니다.

Apispec을 선택하는 이유는 무엇입니까?

  • 간단하고 사용하기 쉬운: Apispec은 간단하고 사용하기 쉬운 API를 제공하므로 빠르게 시작할 수 있습니다.

  • 유연하고 강력함: 여러 프레임워크(예: Flask, Django) 및 확장을 지원하므로 필요에 따라 문서 생성을 사용자 정의할 수 있습니다.

  • 오토메이션: 문서를 자동으로 생성하고 업데이트하여 수동 운영 및 유지 관리 비용을 절감합니다.

설치 및 구성

Apispec을 사용하기 전에 먼저 설치해야 합니다. pip를 사용하여 설치할 수 있습니다.

pip install apispec

Github 프로젝트 주소:

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

02APIspec의 기본 사용법

몇 가지 간단한 예를 통해 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 프로젝트 구성

settings.py에 Rest_framework 및 apispec을 추가합니다.

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

03APIspec의 고급 기능

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은 Flask, Django, Falcon 등과 같은 널리 사용되는 다양한 Python 프레임워크를 지원합니다. 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. 종속성 설치

요구사항.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

생성된 API 문서를 보려면 http://localhost:5000/swagger/를 방문하세요.

05모범 사례

1. 문서와 코드를 동기화 상태로 유지하세요

문서와 실제 API 간의 불일치를 방지하려면 문서가 항상 코드와 동기화되어 있는지 확인하세요. CI/CD 도구를 사용하여 문서를 자동으로 생성하고 배포할 수 있습니다.

2. 주석과 데코레이터를 사용하세요

주석과 데코레이터를 사용하면 문서를 더욱 간결하고 읽기 쉽게 만들 수 있습니다. 예를 들어 Flask-Apispec의 @doc 데코레이터를 사용하여 보기 기능에 문서 정보를 추가합니다.

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 등 다양한 언어에 능숙하며, 오픈 소스 분야에 많은 공헌을 했습니다. 나중에 참조할 수 있도록 기술 개발의 일부 문제를 공유하는 개발자 문서 스테이션입니다.

내 연락처 정보

우편