protodocs

protodocs is an ASGI application that serves documentation for Connect-Python services written in Python. The client is the same as the excellent Armeria docs client, with the server-side handling of specification requests reimplemented with ASGI using starlette.

Setup

Install the package from PyPi and initialize the endpoint with protodocs_app. You can use starlette to serve it together with your service.

uv add protodocs

from pathlib import Path

from protodocs import protodocs_app
from starlette.applications import Starlette
from starlette.routing import Mount

from .gen.greet_connect import GreetService, GreetServiceASGIApplication
from .gen.greet_pb2 import Greeting, GreetingRequest, GreetingResponse
from ._service import ExampleGreetService

greeting_app = GreetServiceASGIApplication(ExampleGreetService())
descriptors = (Path(__file__).parent / "descriptorset.pb").read_bytes()
docs_app = protodocs_app(
    services=greeting_app.path,
    serialized_descriptors=descriptors,
    example_requests={
        f"{greeting_app.path}/Greet": [
            GreetingRequest(greeting=Greeting(nickname="Choko")),
            GreetingRequest(greeting=Greeting(known_name=Greeting.KnownName.BOB)),
        ]
    },
)


app = Starlette(
    routes=[Mount(greeting_app.path, greeting_app), Mount("/internal/docs", docs_app)]
)

Documentation will be served on http://localhost:8080/docs/ and debug requests will be served by the registered handler. Note that services are registered to documentation by name as there is no way to introspect what connect services have been registered on a mux. If the service name(s) used when initializing the plugin do not match the actual handlers, documentation will be served for the unrelated service and debug requests will fail.

Also see a full example here.

Descriptor Set

The app can utilize a serialized descriptor set to augment documentation with the comments from a proto source file. It is strongly recommended to do this to make the documentation more useful.

A descriptor set can be generated by protoc together with any other code. Source info and imports must be included.

protoc --descriptor_set_out=descriptors.pb --include_source_info --include_imports --proto_path=. --go_out=. greet.proto

The serialized descriptors can be loaded with the serialized_descriptors argument to protodocs_app.