Decorators

TornOpen provides some function decorators to provide OpenAPI information.

Tags

With the OpenAPI Specifications, operations can grouped by tags. The tags decorator allows you to add one or more tags to an operation and the resulting spec will be tagged accordingly.

Example

from tornado.web import url
from torn_open import AnnotatedHandler, tags, Application, ResponseModel

class AResponseModel(ResponseModel):
    "This can be ignored"
    pass


class TaggedRequestHandler(AnnotatedHandler):
    @tags("tag_1", "tag_2")
    def get(self) -> AResponseModel:
        pass

app = Application([url("/tagged", TaggedRequestHandler)])

Spec output

info:
  title: tornado-server
  version: 1.0.0
openapi: 3.0.0
paths:
  /tagged:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                description: This can be ignored
                properties: {}
                title: AResponseModel
                type: object
          description: This can be ignored
      tags:
        - tag_1
        - tag_2

Summary

The summary provides a short description for an operation. By default, if the sumary is not provided, ReDoc uses the long description, which is not always ideal. The summary decorator allows you to add a summary to an operation.

Example

from tornado.web import url
from torn_open import AnnotatedHandler, summary, Application, ResponseModel

class AResponseModel(ResponseModel):
    "This can be ignored"
    pass


class SummaryRequestHandler(AnnotatedHandler):
    @summary("This is a short description of the operation")
    def get(self) -> AResponseModel:
        pass

app = Application([url("/summary", SummaryRequestHandler)])

Spec output

info:
  title: tornado-server
  version: 1.0.0
openapi: 3.0.0
paths:
  /summary:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                description: This can be ignored
                properties: {}
                title: AResponseModel
                type: object
          description: This can be ignored
      summary: This is a short description of the operation