How to deal with large APIs

[Sytten]

I was wondering how to deal with large APIs considering all the handlers and models needs to be referenced by the ApiDoc meta object.
Coming from actix, I have a bunch of modules that each contain a config function.
Ideally I would like to keep that clean separation of concerns and have a Documentation object beside each of them and then re-group them all at a higher level so I don't have to make everything public.

Thanks!

[Sytten]

I built something custom that works for basic cases:

pub fn build_open_api() -> OpenApi {
    let all_documentations = [
        webhook::Documentation::openapi(),
        health::Documentation::openapi(),
    ];

    let mut all_components = ComponentsBuilder::new();
    let mut all_paths = PathsBuilder::new();
    for documentation in all_documentations {
        // Merge components
        if let Some(components) = documentation.components {
            all_components = all_components.components_from_iter(components.schemas);
            for (name, scheme) in components.security_schemes {
                all_components = all_components.security_scheme(name, scheme);
            }
        }

        // Merge paths
        for (path, item) in documentation.paths.paths {
            all_paths = all_paths.path(path, item);
        }
    }

    OpenApiBuilder::new()
        .info(
            InfoBuilder::new()
                .title("portal-backend")
                .version("0.1.0")
                .build(),
        )
        .paths(all_paths.build())
        .components(Some(all_components.build()))
        .build()
}

I think a "merge" function build-in would be very useful.

[juhaku]

Yes I agree, a way to compose multiple docs to single OpenAPI representation would be beneficial but not supported at the moment unfortunately.

[juhaku]

That is something probably needs some engineering effort to get right. Currently there is no "by the book" answer to this and it probably is something to be experimented. Keeping modules tidy by not exposing everything to the whole world would be ideal though I'm afraid that at the moment isolating modules completely is not possible. I've had a plan to actually write a larger example with acitx-web but so far the priority has been in the library itself.

Since the OpenApi derive macro need to be aware of the components and paths the OpenAPI doc will be generated from at compile time it must have access to the types and handlers. Also at the moment there is no way to compose OpenAPI doc from multiple OpenApi derived structs. All this leads to having handlers and types exposed to the type having OpenApi derive attribute. If it is kept in root module then it indeed means having handlers and types exposed as public.

As discovered above there is a need to compose multiple OpenApi derive structs to a single OpenAPI doc which in turn would allow users to only expose the doc outside their modules letting users to keep everything else private to the modules. I'll add a note to the project's kanban board about this so I'll remember to work on this in future. :)

[Sytten]

All good, my method works good enough for my use case. There is most likely some stuff that can't be achieved with this simple merge so yeah definitely need some thought to make the feature available in the lib.