Skip to content
PERSEUS

API documentation

To add service-specific OpenAPI documentation, PERSEUS offers several methods and the documentation module to handle the API documentation.

The BaseService class offers following methods to add service-specific documentation:

  • BaseService.add_get_documentation()
  • BaseService.add_post_documentation()
  • BaseService.add_delete_documentation()

All methods are expecting an object from class perseus.documentation.EndpointDocumentation.

In order for PERSEUS to update the documentation when initializing, documentation must be created within the initialize method.

Endpoint documentation

Section titled “Endpoint documentation”

  1. Add endpoint

    custom/MyService.py
    from perseus.documentation import (
        EndpointDocumentation,
    )
    

    

    class MyService(BaseService):
        ...
        @classmethod
        def initialize(cls):
            ...
            get_specific_template = EndpointDocumentation("{template_oid}", "Get a specific Template using the object id")

  2. Add required or optional parameter

    custom/MyService.py
    from perseus.documentation import (
        EndpointDocumentation,
        EndpointDocumentationParameter,
        EndpointDocumentationPropertyType,
    )
    

    ...
    

    get_specific_template.add_parameter(
        EndpointDocumentationParameter(
            "template_oid",
            description="The object id of the template",
            parameter_type="path",
            property_type=EndpointDocumentationPropertyType.STRING,
            required=True,
        ),
    )

  3. Add endpoint response

    custom/MyService.py
    from perseus.documentation import (
        EndpointDocumentation,
        EndpointDocumentationParameter,
        EndpointDocumentationPropertyType,
        EndpointDocumentationProperty,
    )
    

    ...
    

    get_specific_template.add_response(
        200,
        "Action was completed successfully",
        [
            EndpointDocumentationProperty(
                "object",
                EndpointDocumentationPropertyType.OBJECT,
                properties=[
                    EndpointDocumentationProperty(
                        "_id",
                        EndpointDocumentationPropertyType.STRING,
                    ),
                    EndpointDocumentationProperty(
                        "template_id",
                        EndpointDocumentationPropertyType.STRING,
                    ),
                    EndpointDocumentationProperty(
                        "name",
                        EndpointDocumentationPropertyType.STRING,
                    ),
                    EndpointDocumentationProperty(
                        "content",
                        EndpointDocumentationPropertyType.STRING,
                    ),
                    EndpointDocumentationProperty(
                        "email_template_type",
                        EndpointDocumentationPropertyType.STRING,
                    ),
                ],
            ),
        ],
        {
            "_id": "6sd887aa074764742871aaff",
            "template_id": "welcome_mail",
            "name": "User welcome mail",
            "content": "{greeting}\n\nProject start: {projectstart}\n\nProject end: {projectend}",
            "email_template_type": "EXTERNAL",
        },
    )

  4. Register EndpointDocumentation to service

    custom/MyService.py
    ...
    MyService.add_get_documentation(get_specific_template)