Flask-RESTful은 파이썬에서 API를 개발하기 위한 프레임워크로, 간단하고 편리한 API 개발을 지원합니다. 이 프레임워크를 사용하여 개발한 API를 문서화하는 방법을 알아보겠습니다.

Swagger UI를 통한 자동문서화

Flask-RESTful에서는 Swagger UI를 사용하여 API를 자동으로 문서화할 수 있습니다. Swagger UI는 API의 엔드포인트, 요청 및 응답의 형식, 매개변수 등을 시각적으로 표현하여 개발자에게 API의 사용법을 안내해줍니다.

먼저 Flask-RESTful과 함께 Flask-RESTplus 라이브러리를 설치해야 합니다. 다음 명령어를 사용하여 설치합니다:

pip install flask-restful flask-restplus

다음으로 Swagger UI를 사용하여 API를 문서화해야 합니다. Flask-RESTplus는 매우 간단한 방법으로 Swagger UI를 통합할 수 있도록 지원합니다. 다음은 Flask-RESTplus를 사용하여 Swagger UI를 활성화하는 예제입니다:

from flask import Flask
from flask_restplus import Api, Resource

app = Flask(__name__)
api = Api(app)

@api.route('/example')
class ExampleResource(Resource):
    def get(self):
        '''API 예제'''
        return {'message': 'Hello, World!'}

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

위 예제에서는 “/example” 엔드포인트에 대한 예제 리소스를 정의합니다. get 메서드는 “API 예제”라는 문서화 주석을 가지고 있습니다. 이 주석은 Swagger UI에서 API 설명으로 표시됩니다.

API를 실행한 뒤, 브라우저에서 http://localhost:5000/api/ 에 접속하면 Swagger UI를 통해 문서화된 API를 확인할 수 있습니다.

Pydoc를 통한 수동 문서화

Swagger UI를 사용하여 자동으로 API를 문서화하는 대신에, 개발자가 직접 API를 문서화하고 싶을 경우, 파이썬 기본 도구 중 하나인 Pydoc를 사용할 수 있습니다.

Pydoc는 소스 코드에 포함된 docstring(문서화용 문자열)을 추출하여 API 문서를 생성하는 기능을 제공합니다. Flask-RESTful에서는 다음과 같은 방법으로 Pydoc를 사용하여 API를 문서화할 수 있습니다:

from flask import Flask
from flask_restful import Api, Resource

app = Flask(__name__)
api = Api(app)

class ExampleResource(Resource):
    def get(self):
        """
        API 예제

        이 API는 HelloWorld를 반환합니다.
        """
        return {'message': 'Hello, World!'}

api.add_resource(ExampleResource, '/example')

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

위 예제에서는 get 메서드의 docstring을 사용하여 API를 문서화하였습니다. 이 docstring은 Pydoc를 실행하여 문서화된 API를 생성할 때 사용됩니다. Pydoc를 사용하여 API를 문서화하려면 다음 명령어를 사용합니다:

python -m pydoc -w your_module_name

위 명령어를 실행하면 현재 작업 디렉토리에 your_module_name.html 파일이 생성됩니다. 이 파일을 웹 브라우저로 열면 문서화된 API를 확인할 수 있습니다.

결론

Flask-RESTful을 사용하여 개발한 API를 문서화하는 방법에 대해 알아보았습니다. Swagger UI를 사용하여 자동으로 API를 문서화하거나, Pydoc를 사용하여 개발자가 직접 문서화할 수 있습니다. 많은 개발자들이 편리한 Swagger UI를 선호하지만, 경우에 따라 직접 문서화를 해야할 수도 있습니다. API 문서화는 개발자와 협업자들에게 API 사용법을 쉽게 전달할 수 있는 방법이므로 중요합니다.