Add nest OpenApi support
#930
Conversation
juhaku
force-pushed
the
feature-nest-openapi-support
branch
from
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
juhaku
force-pushed
the
feature-nest-openapi-support
branch
from
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_pathattribute on#[utoipa::path]macro but this functionality undoes the need forcontext_pathin most cases.Add
nest(...)method toOpenApito allow nesting of otherOpenApiinstances to the currentOpenApiinstance.Add
nestattribute toOpenApiderive macro.Resolves #445 Resolves #872