백엔드 개발 일지

REST API는 현대 웹 애플리케이션에서 중요한 역할을 합니다. API의 명세를 문서화하는 것은 유지보수와 협업에 큰 도움이 되지만, 수동으로 문서화하는 것은 번거롭고 실수가 발생하기 쉽습니다. 이번 글에서는 Python을 사용하여 REST API 문서화를 자동화하는 방법에 대해 알아보겠습니다.

필요한 라이브러리 설치

우선, API 문서화를 자동화하기 위해 필요한 라이브러리를 설치하겠습니다. Flask를 사용하여 API를 구성하고, Flask-RESTPlus를 통해 문서화를 쉽게 할 수 있습니다. 다음 명령어로 두 라이브러리를 설치합니다.

pip install Flask Flask-RESTPlus

기본적인 Flask API 설정

먼저, 기본적인 Flask 애플리케이션을 설정해보겠습니다. 아래 코드를 app.py 파일에 작성합니다.

from flask import Flask
from flask_restplus import Api, Resource

app = Flask(__name__)
api = Api(app, version='1.0', title='My API',
          description='A simple demonstration of a REST API')

ns = api.namespace('tasks', description='Task operations')

tasks = [
    {'id': 1, 'task': 'Build an API'},
    {'id': 2, 'task': '?????'},
    {'id': 3, 'task': 'Profit!'},
]

@ns.route('/<int:id>')
@ns.response(404, 'Task not found')
@ns.param('id', 'The task identifier')
class Task(Resource):
    def get(self, id):
        '''Fetch a task given its identifier'''
        for task in tasks:
            if task['id']  id:
                return task
        api.abort(404)

    def delete(self, id):
        '''Delete a task given its identifier'''
        global tasks
        tasks = [task for task in tasks if task['id'] != id]
        return '', 204

@ns.route('/')
class TaskList(Resource):
    def get(self):
        '''List all tasks'''
        return tasks

    def post(self):
        '''Create a new task'''
        new_task = {'id': len(tasks) + 1, 'task': 'New Task'}
        tasks.append(new_task)
        return new_task, 201

if __name__  '__main__':
    app.run(debug=True)

위 코드는 간단한 REST API를 설정합니다. /tasks/ 엔드포인트는 모든 작업을 목록으로 가져오고, 새 작업을 추가할 수 있습니다. /tasks/<id> 엔드포인트는 특정 작업을 조회하거나 삭제하는 기능을 제공합니다.

Swagger UI로 문서화하기

Flask-RESTPlus는 자동으로 Swagger UI를 통해 API 문서를 생성해줍니다. API 서버를 실행한 후에, 웹 브라우저에 http://127.0.0.1:5000/를 입력하면 Swagger UI에 접근할 수 있습니다. 여기서 API의 모든 엔드포인트를 확인하고, 요청을 테스트할 수 있습니다.

추가 문서화 기능

Flask-RESTPlus는 다양한 데코레이터를 제공하여 API 문서화에 유용합니다. 예를 들어, 다음과 같이 요청 및 응답 모델을 정의하여 문서를 더욱 풍부하게 만들 수 있습니다.

from flask_restplus import fields

task_model = api.model('Task', {
    'id': fields.Integer(readonly=True, description='The task unique identifier'),
    'task': fields.String(required=True, description='The task details')
})

@ns.route('/<int:id>')
class Task(Resource):
    @ns.doc('get_task')
    @ns.marshal_with(task_model)
    def get(self, id):
        '''Fetch a task given its identifier'''
        # ... (기존 코드)

    @ns.doc('delete_task')
    @ns.response(204, 'Task deleted')
    def delete(self, id):
        '''Delete a task given its identifier'''
        # ... (기존 코드)

@ns.route('/')
class TaskList(Resource):
    @ns.doc('list_tasks')
    @ns.marshal_list_with(task_model)
    def get(self):
        '''List all tasks'''
        # ... (기존 코드)

    @ns.doc('create_task')
    @ns.expect(task_model)
    @ns.marshal_with(task_model, code=201)
    def post(self):
        '''Create a new task'''
        # ... (기존 코드)

위 코드에서 task_model을 정의하여 작업의 형식을 지정했습니다. 각 엔드포인트에 대한 설명과 응답 형식을 추가하면 문서의 가독성이 높아집니다.

마무리

이번 튜토리얼에서는 Python을 이용하여 REST API를 구성하고, Flask-RESTPlus를 활용하여 자동으로 API 문서를 생성하는 방법에 대해 알아보았습니다. 코드 예제를 통해 간단한 API를 설정하고 Swagger UI를 통해 문서화하는 과정을 살펴보았습니다. 이 방법을 통해 개발자는 API 문서화에 소요되는 시간을 단축하고, 팀원들과의 협업을 더욱 원활하게 할 수 있습니다. 추가적으로 더 복잡한 API를 구성하고 문서화할 때에도 Flask-RESTPlus의 기능을 활용하면 효율적인 개발이 가능하니, 여러분의 프로젝트에 적용해보시길 추천드립니다.

Python으로 REST API 문서화 자동화하는 방법 튜토리얼

필요한 라이브러리 설치

기본적인 Flask API 설정

Swagger UI로 문서화하기

추가 문서화 기능

마무리