Flask-RESTX Swagger를 이용한 문서화

localhost에 들어가면 기본적으로 문서화가 되어있다.

 

app.py

from flask import Flask
from flask_restx import Resource, Api
from todo import Todo

app = Flask(__name__)
api = Api(
    app,
    version='0.1',
    title="nam's api server",
    description="nanam's Todo API Server!",
    terms_url="/",
    contact="riotgames@kakao.com",
    license="MIT"
)

api.add_namespace(Todo, '/todos')

if __name__ == "__main__":
    app.run(debug=True, host='0.0.0.0', port=80)

todo.py

from xml.dom import NamespaceErr
from flask import request
from flask_restx import Resource, Namespace, fields


todos = {}
count = 1



Todo = Namespace("Todo",description="나는바보다!!!")
todo_fields = Todo.model('Todo', {  # Model 객체 생성
    'data': fields.String(description='a Todo', required=True, example="what to do")
})

todo_fields_with_id = Todo.inherit('Todo With ID', todo_fields, {  # todo_fields 상속 받음
    'todo_id': fields.Integer(description='a Todo ID')
})
@Todo.marshal_with(todo_fields_with_id, as_list=True)



@Todo.route('')
class TodoPost(Resource):
    def post(self):
        """이게된다고?"""
        global count
        global todos
        
        idx = count
        count += 1
        todos[idx] = request.json.get('data')
        
        return {
            'todo_id': idx,
            'data': todos[idx]
        }

@Todo.route('/<int:todo_id>')
@Todo.doc(params={'todo_id': 'mynam'})
class TodoSimple(Resource):
    def get(self, todo_id):
        """정말?"""
        return {
            'todo_id': todo_id,
            'data': todos[todo_id]
        }

    def put(self, todo_id):
        """굉장해!!"""
        todos[todo_id] = request.json.get('data')
        return {
            'todo_id': todo_id,
            'data': todos[todo_id]
        }

    @Todo.doc(responses={202: 'Success'})
    @Todo.doc(responses={500: 'Failed'})
    def delete(self, todo_id):
        """엄청나!!"""
        del todos[todo_id]
        return {
            "delete" : "success"
        }

app.py의 소스코드중

api.add_namespace(Todo, '/todos')​

이 부분이 분리된 문서를 연결하는 부분이다.

인자중 Todo는 

Todo = Namespace("Todo",description="나는바보다!!!")

todo.py의 소스코드중 만들어진 Todo 변수와 연결이 되고

 

인자중 '/todos'는

@Todo.route('/<int:todo_id>')

다음과 같은 route하는 부분과 연결이 된다. 즉 위의 소스의 경우 /todos/<int:todo_id>가 되는셈이다.

 

api = Api(
    app,
    version='0.1',
    title="nam's api server",
    description="nanam's Todo API Server!",
    terms_url="/",
    contact="riotgames@kakao.com",
    license="MIT"
)

• version: API Server의 버전을 명시합니다.
• title: API Server의 이름을 명시합니다.
• description: API Server의 설명을 명시합니다.
• terms_url: API Server의 Base Url을 명시합니다.
• contact: 제작자 E-Mail 등을 삽입합니다.
• license: API Server의 라이센스를 명시 합니다.
• license_url: API Server의 라이센스 링크를 명시 합니다.

다음처럼 api에 대한 명시를 해줄수있다.

사진처럼 반영이 된다.

 

Todo = Namespace("Todo",description="나는바보다!!!")

namespace에 대해 서술할수있다.

• title: Namespace의 이름을 명시합니다.
• description: Namespace의 설명을 명시합니다.

다음처럼 반영이 된다.

 def post(self):
        """이게된다고?"""

다음처럼 함수내에 파이썬에서 주석으로 쓰이는 """가 인식되어 함수를 서술한다.

 

todo_fields = Todo.model('Todo', {  # Model 객체 생성
    'data': fields.String(description='a Todo', required=True, example="what to do")
})

todo_fields_with_id = Todo.inherit('Todo With ID', todo_fields, {  # todo_fields 상속 받음
    'todo_id': fields.Integer(description='a Todo ID')
})

다음처럼 모델 객체를 통해 필드를 만들어 줄수있고 inherit을 이용해 만든 필드를 상속받아 이어 쓸수있다.

자동으로 표시된다 하는데 나는 자동으로 안됐다

@Todo.marshal_with(todo_fields_with_id, as_list=True)

다음구문을 써서 명시적으로 올려야 표시가 됐다.

@Todo.response(200, 'Success', todo_fields_with_id)

response에 모델 객체를 넣어줘도 정상적으로 표시된다.

상속받은 데이터형식까지 보여지는 모습

 

@Todo.doc(params={'todo_id': 'mynam'})
class TodoSimple(Resource):

데코레이터를 통해 들어가는 파라미터를 서술할수있게된다.

• params: dict 객체를 받으며, 키로는 파라미터 변수명, 값으로는 설명을 적을 수 있습니다.

todo_id가 mynam으로 표시되는 모습

 

@Todo.doc(responses={202: 'Success'})
    @Todo.doc(responses={500: 'Failed'})

• responses: dict 객체를 받으며, 키로는 Status Code, 값으로는 설멍을 적을 수 있습니다.

response의 값이 서술된 모습

 

Namespace.expect(),Namespace.response()등 다양한 기능들이 더 많지만 필요할때 보는게 좋아보인다.

 

https://docker.apachezone.com/blog/35?page=5 

Flask-RESTX Swagger documentation > 블로그(Blog) | 도커 아파치존

 

더 많은 기능들을 보기위한 사이트

https://justkode.kr/python/flask-restapi-2

Flask로 REST API 구현하기 - 2. 파일 분리, 문서화

해당내용에 대한 설명이 잘되어 있는 곳

https://flask-restx.readthedocs.io/en/latest/swagger.html#documenting-the-fields

Swagger documentation — Flask-RESTX 0.5.2.dev documentation