-
Notifications
You must be signed in to change notification settings - Fork 202
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add nest OpenApi
support
#930
Conversation
7af36bd
to
58ad85e
Compare
This PR implements API nesting support to enable modular OpenAPI specification declaration. This functionality is implemented at OpenApi type itself as well as at OpenApi derive trait. Prior to this PR there was no simple way to modularize the OpenApi definition and one way to do this was to use `context_path` attribute on `#[utoipa::path]` macro but this functionality undoes the need for `context_path` in most cases. Add `nest(...)` method to `OpenApi` to allow nesting of other `OpenApi` instances to the current `OpenApi` instance. ```rust let api = OpenApiBuider::new().build(); let nested = api.nest("/nest/path", OpenApiBuilder::new().build()); ``` Add `nest` attribute to `OpenApi` derive macro. ```rust #[derive(OpenApi)] #[openapi( paths(...), nest( ("path/to/nest", NestableApi) ) )] struct RootApi; ``` Resolves #445 Resolves #872
58ad85e
to
07925da
Compare
This commits enhances the `OpenApi` nesting support by adding possiblity to define `tags [...]` for the nested OpenApi endpoints. By default the fully qualified path to the nested `OpenApi` will become the tag for the endpoints if provided. This commit also makes it necessary to define the argument names within the nest tuple to be constant across the utoipa macros and more readable. `Path` and `api` arguments are necesary. Supported nesting syntax: ```rust (path = "/path/to/nest/api", api = path::to:NestableApi, tags = [...]) ``` **Breaking!** This is breaking change as this changes the `utoipa::Path` trait syntax to following. Prior this commit the the `path_item` function took `Option<&str>`parameter to define default `tag` for the path operation but this is no longer necessary. ```rust trait Path { fn path() -> String; fn path_item() -> PathItem; } ``` Follow up PR for #930 Resolves #445 Resolves #872
This commits enhances the `OpenApi` nesting support by adding possibility to define `tags [...]` for the nested OpenApi endpoints. By default the fully qualified path to the nested `OpenApi` will become the tag for the endpoints if provided. This commit also makes it necessary to define the argument names within the nest tuple to be constant across the utoipa macros and more readable. `Path` and `api` arguments are necessary. Supported nesting syntax: ```rust (path = "/path/to/nest/api", api = path::to:NestableApi, tags = [...]) ``` **Breaking!** This is breaking change as this changes the `utoipa::Path` trait syntax to following. Prior this commit the `path_item` function took `Option<&str>` parameter to define default `tag` for the path operation but this is no longer necessary. ```rust trait Path { fn path() -> String; fn path_item() -> PathItem; } ``` Follow up PR for #930 Resolves #445 Resolves #872
@juhaku Hi! Is it available on cargo? Because compiler says |
UPDATE: yes, the feature is not released yet. But I think I left my comment, in case anyone has this problem |
@InAnYan Yes it is there, but as you said it has not been released officially yet. It is in the current beta |
@juhaku is there a predicted date when this function will be available? I just got here because in the |
The
There is no set date for it to come out officially, but should be soon enough nonetheless. Most of the functionality should be there while some work still remains. |
This PR implements API nesting support to enable modular OpenAPI specification declaration. This functionality is implemented at OpenApi type itself as well as at OpenApi derive trait. Prior to this PR there was no simple way to modularize the OpenApi definition and one way to do this was to use
context_path
attribute on#[utoipa::path]
macro but this functionality undoes the need forcontext_path
in most cases.Add
nest(...)
method toOpenApi
to allow nesting of otherOpenApi
instances to the currentOpenApi
instance.Add
nest
attribute toOpenApi
derive macro.Resolves #445 Resolves #872