aiohttp-apispec-plugin

Lightweight apispec plugin that generates OpenAPI specification for aiohttp web applications.

Installation

pip install aiohttp-apispec-plugin

Examples

With class based view

from aiohttp import web
from aiohttp_apispec_plugin import AioHttpPlugin
from apispec import APISpec

class UserView(web.View):
    async def get(self) -> web.Response:
        """User Detail View
        ---
        summary: Get User
        description: Get User Data For Given `user_id`
        parameters:
        - name: user_id
          in: path
          description: User ID
          required: true
          schema:
            type: string
        responses:
          200:
            description: Successfully retrieved user details
            content:
              application/json:
                schema:
                  properties:
                    id:
                      type: integer
                    username:
                      type: string
                    first_name:
                      type: string
                    last_name:
                      type: string
        """

app = web.Application()
app.router.add_view("/api/v1/users/{user_id}", UserView)

# Create an APISpec
spec = APISpec(
    title="AioHttp Application",
    version="1.0.0",
    openapi_version="3.0.3",
    plugins=[
        AioHttpPlugin(app),
    ],
)

spec.path(resource=UserView)
print(spec.to_yaml())
"""
info:
  title: AioHttp Application
  version: 1.0.0
openapi: 3.0.3
paths:
  /api/v1/users/{user_id}:
    get:
      description: Get User Data For Given `user_id`
      parameters:
      - description: User ID
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  first_name:
                    type: string
                  id:
                    type: integer
                  last_name:
                    type: string
                  username:
                    type: string
          description: Successfully retrieved user details
      summary: Get User
"""

With function based view

from aiohttp import web
from aiohttp_apispec_plugin import AioHttpPlugin
from apispec import APISpec

async def get_user(request: web.Request) -> web.Response:
    """User Detail View
    ---
    summary: Get User
    description: Get User Data For Given `user_id`
    responses:
      200:
        description: Successfully retrieved user details
    """

app = web.Application()
app.router.add_get("/api/v1/users/{user_id}", get_user)

# Create an APISpec
spec = APISpec(
    title="AioHttp Application",
    version="1.0.0",
    openapi_version="3.0.3",
    plugins=[
        AioHttpPlugin(app),
    ],
)

spec.path(resource=get_user)
print(spec.to_yaml())  # same behavior

With dataclasses plugin

from dataclasses import dataclass
from aiohttp import web
from aiohttp_apispec_plugin import AioHttpPlugin
from apispec import APISpec
from dataclasses_jsonschema import JsonSchemaMixin
from dataclasses_jsonschema.apispec import DataclassesPlugin

@dataclass
class User(JsonSchemaMixin):
    """User Schema"""
    id: int
    username: str

async def get_user(request: web.Request) -> web.Response:
    """User Detail View
    ---
    summary: Get User
    description: Get User Data For Given `user_id`
    responses:
      200:
        description: Successfully retrieved user details
        content:
            application/json:
                schema: User
    """

app = web.Application()
app.router.add_get("/api/v1/users/{user_id}", get_user)

spec = APISpec(
    title="AioHttp Application",
    version="1.0.0",
    openapi_version="3.0.3",
    plugins=[
        AioHttpPlugin(app),
        DataclassesPlugin(),
    ],
)

spec.components.schema("User", schema=User)
spec.path(resource=get_user)

print(spec.to_yaml())
"""
components:
  schemas:
    User:
      description: User Schema
      properties:
        id:
          type: integer
        username:
          type: string
      required:
      - id
      - username
      type: object
info:
  title: AioHttp Application
  version: 1.0.0
openapi: 3.0.3
paths:
  /api/v1/users/{user_id}:
    get:
      description: Get User Data For Given `user_id`
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successfully retrieved user details
      summary: Get User
"""

Requirements

Python >= 3.6

Dependencies:

• aiohttp
• apispec
• PyYAML

Other libs to check

• aiohttp-apispec
• falcon-apispec
• dataclasses-jsonschema