Figure out how to create API documentation

[yalgorithm777]

We need to figure out how to create API documentation pages. For example, check http://flasgger.pythonanywhere.com/

[Loooffy]

I'm recently working on a nest.js project, and am impressed by the way it use decorator to define clarified OpenApi spec within the source code.

There are packages which could help us achieve the similar 'smell' for Flask. They are flask-restful and flask-apispec. I found them on this post.

The source code of the provided example below shows the trick.

First, a pair of req/res Schema define the spec of interfaces such as data type, default value etc., and then implemented using use_kwargs, marshal_with decorators by the API handler.

This declarative pattern enable us to define the implementation and spec of an API at the same place.

# 1. Define the pair of req/res Schema of the API

class AwesomeResponseSchema(Schema):
    message = fields.Str(default='Success')

class AwesomeRequestSchema(Schema):
    api_type = fields.String(required=True, description="API type of awesome API")

# 2. Implement them with use_kwargs, marshal_with decorators right above the handler

class AwesomeAPI(MethodResource, Resource):
    @doc(description='My First GET Awesome API.', tags=['Awesome'])
    @use_kwargs(AwesomeRequestSchema, location=('json'))
    @marshal_with(AwesomeResponseSchema)  # marshalling
    def post(self, **kwargs):
        '''
        Get method represents a GET API method
        '''
        return {'message': 'My First Awesome API'}

With these simple gadgets, we can get a basic Swagger UI like this.

[arati-1]

Hello,

I am arati, a technical writer interested to contribute for your REST API documentation.

I saw that you need help with your API documentation. May be I can help you with that.

I saw your readme.md and saw API calls section, is that the only Api call you need documentation for, or there is more?

Let me know if you need help and how I can get started. I can write the documentation in markdown file and share it with you for the Get the unique user token from the system API. If you feel that is what your are looking for then I can collaborate.

Regards, Arati