Generating Docs

Lambda Forge excels not only in structuring Lambda functions for scalability but also in facilitating the automatic documentation of key project components. It simplifies the deployment of documents to the cloud, making them readily accessible via API Gateway.

Documentation is seamlessly generated through CodePipeline and is then deployed to the S3 Bucket defined within your cdk.json file. This automated process ensures your project's documentation is always up-to-date and easily accessible.

Available Docs

The table below lists the documentation generated by this tutorial, accessible via API Gateway endpoints.

Swagger	Redoc	Diagram
Coverage	Tests	Wiki

API Documentation with Swagger and ReDoc

To automatically document your api endpoints with Swagger and Redoc, you should include the Input and Output dataclasses inside your main.py files. Case you have an endpoint that's expecting a path parameter, you can also include it in the Path dataclass.

The code snippet below demonstrates all the types of data you can expect to work with, including simple data types, lists, custom objects, optional fields, and literal types, offering a clear understanding of the input and output contracts for the API.

main.py

from dataclasses import dataclass
from typing import List, Optional, Literal

@dataclass
class Path:
    id: str

@dataclass
class Object:
    a_string: str
    an_int: int

@dataclass
class Input:
    a_string: str  
    an_int: int  
    a_boolean: bool  
    a_list: List[str]  
    an_object: Object  
    a_list_of_object: List[Object]  
    a_literal: Literal["a", "b", "c"]  
    an_optional: Optional[str]  


@dataclass
class Output:
    pass 

def lambda_handler(event, context):

    return {
        "statusCode": 200,
        "body": json.dumps({"message": "Hello Docs!"})
    }

Diagram

To view the current architecture diagram of your application, run the following command in your terminal:

forge diagram

This command generates a PNG file depicting your current architecture, including all triggers and invocations, as shown below:

Setting Up the Endpoints

The endpoints to visualize your docs are configured within docs/config.py. This configuration file allows you to specify the types of documents to be displayed and their presentation locations.

Similar to functions, authorizers can be implemented to safeguard the access to your project's documentation, maintaining its confidentiality and integrity.

docs/config.py

from infra.services import Services

class DocsConfig:
    def __init__(self, services: Services) -> None:
        # Public Swagger at /swagger
        services.api_gateway.create_docs(endpoint="/swagger", artifact="swagger", public=True)

        # Private Swagger at /swagger
        services.api_gateway.create_docs(endpoint="/private/swagger", artifact="swagger", authorizer="secret")

        # Redoc at /redoc
        services.api_gateway.create_docs(endpoint="/redoc", artifact="redoc", public=True)

        # Architecture Diagram at /diagram
        services.api_gateway.create_docs(endpoint="/diagram", artifact="diagram", public=True)

        # Tests Report at /tests
        services.api_gateway.create_docs(endpoint="/tests", artifact="tests", public=True)

        # Coverage Report at /coverage
        services.api_gateway.create_docs(endpoint="/coverage", artifact="coverage", public=True)

        # Wiki at /wiki
        # Use the Wiki's title as artifact
        services.api_gateway.create_docs(endpoint="/wiki", artifact="Wiki", public=True)