From 7e493444572c639eb85d903cf5eeab690f01c4ea Mon Sep 17 00:00:00 2001 From: John Vandenberg Date: Mon, 4 Dec 2023 01:18:23 +0800 Subject: [PATCH] Misc document improvements (#814) --- README.md | 50 ++++++++++++++++++---------------- utoipa-gen/src/lib.rs | 30 ++++++++++---------- utoipa-rapidoc/src/lib.rs | 2 +- utoipa-redoc/src/lib.rs | 18 ++++++------ utoipa-swagger-ui/src/lib.rs | 16 +++++------ utoipa-swagger-ui/src/oauth.rs | 12 ++++---- utoipa/src/lib.rs | 2 +- utoipa/src/openapi/info.rs | 4 +-- utoipa/src/openapi/path.rs | 12 ++++---- utoipa/src/openapi/response.rs | 2 +- utoipa/src/openapi/schema.rs | 12 ++++---- utoipa/src/openapi/security.rs | 7 ++--- utoipa/src/openapi/tag.rs | 2 +- utoipa/src/openapi/xml.rs | 4 +-- 14 files changed, 87 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index aac1595a..ef2ad4e8 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ and the `ipa` is _api_ reversed. Aaand... `ipa` is also an awesome type of beer it is interpreted as `String`. If you wish to change the format you need to override the type. See the `value_type` in [component derive docs](https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html). - **decimal_float** Add support for [rust_decimal](https://crates.io/crates/rust_decimal) `Decimal` type. **By default** - it is interpreted as `Number`. This feature is mutually exclusive with **decimal** and allow to change the default type used in your + it is interpreted as `Number`. This feature is mutually exclusive with **decimal** and allow to change the default type used in your documentation for `Decimal` much like `serde_with_float` feature exposed by rust_decimal. - **uuid** Add support for [uuid](https://github.com/uuid-rs/uuid). `Uuid` type will be presented as `String` with format `uuid` in OpenAPI spec. @@ -106,14 +106,14 @@ and the `ipa` is _api_ reversed. Aaand... `ipa` is also an awesome type of beer - **indexmap** Add support for [indexmap](https://crates.io/crates/indexmap). When enabled `IndexMap` will be rendered as a map similar to `BTreeMap` and `HashMap`. - **non_strict_integers** Add support for non-standard integer formats `int8`, `int16`, `uint8`, `uint16`, `uint32`, and `uint64`. -- **rc_schema** Add `ToSchema` support for `Arc` and `Rc` types. **Note!** serde `rc` feature flag must be enabled separately to allow +- **rc_schema** Add `ToSchema` support for `Arc` and `Rc` types. **Note!** serde `rc` feature flag must be enabled separately to allow serialization and deserialization of `Arc` and `Rc` types. See more about [serde feature flags](https://serde.rs/feature-flags.html). Utoipa implicitly has partial support for `serde` attributes. See [docs](https://docs.rs/utoipa/latest/utoipa/derive.ToSchema.html#partial-serde-attributes-support) for more details. ## Install -Add minimal dependency declaration to Cargo.toml. +Add minimal dependency declaration to `Cargo.toml`. ```toml [dependencies] @@ -173,6 +173,7 @@ mod pet_api { } } ``` + Utoipa has support for [http](https://crates.io/crates/http) `StatusCode` in responses. _This attribute macro will create another struct named with `__path_` prefix + handler function name. @@ -191,7 +192,7 @@ struct ApiDoc; println!("{}", ApiDoc::openapi().to_pretty_json().unwrap()); ``` -This would produce api doc something similar to: +This would produce an API doc something similar to: ```json { @@ -274,29 +275,31 @@ This would produce api doc something similar to: } ``` - ## Modify OpenAPI at runtime +## Modify OpenAPI at runtime + +You can modify generated OpenAPI at runtime either via generated types directly or using +[Modify](https://docs.rs/utoipa/latest/utoipa/trait.Modify.html) trait. + +_Modify generated OpenAPI via types directly._ - You can modify generated OpenAPI at runtime either via generated types directly or using - [Modify](https://docs.rs/utoipa/latest/utoipa/trait.Modify.html) trait. +```rust +#[derive(OpenApi)] +#[openapi( + info(description = "My Api description"), +)] +struct ApiDoc; - _Modify generated OpenAPI via types directly._ - ```rust - #[derive(OpenApi)] - #[openapi( - info(description = "My Api description"), - )] - struct ApiDoc; +let mut doc = ApiDoc::openapi(); +doc.info.title = String::from("My Api"); +``` - let mut doc = ApiDoc::openapi(); - doc.info.title = String::from("My Api"); - ``` +_You can even convert the generated [OpenApi](https://docs.rs/utoipa/latest/utoipa/openapi/struct.OpenApi.html) to [OpenApiBuilder](https://docs.rs/utoipa/latest/utoipa/openapi/struct.OpenApiBuilder.html)._ - _You can even convert the generated [OpenApi](https://docs.rs/utoipa/latest/utoipa/openapi/struct.OpenApi.html) to [OpenApiBuilder](https://docs.rs/utoipa/latest/utoipa/openapi/struct.OpenApiBuilder.html)._ - ```rust - let builder: OpenApiBuilder = ApiDoc::openapi().into(); - ``` +```rust +let builder: OpenApiBuilder = ApiDoc::openapi().into(); +``` - See [Modify](https://docs.rs/utoipa/latest/utoipa/trait.Modify.html) trait for examples on how to modify generated OpenAPI via it. +See [Modify](https://docs.rs/utoipa/latest/utoipa/trait.Modify.html) trait for examples on how to modify generated OpenAPI via it. ## Go beyond the surface @@ -319,14 +322,13 @@ library **does not** by default embed files on debug builds. To get around this Find `utoipa-swagger-ui` [feature flags here](https://github.com/juhaku/utoipa/tree/master/utoipa-swagger-ui#crate-features). - ### How to implement `ToSchema` for external type? There are few ways around this that are elaborated [here in detail](https://github.com/juhaku/utoipa/issues/790#issuecomment-1787754185). ### How to use Rust's type aliases? -At the moment that is not possible due to there is no way to evaluate the actual type behind the type token that is visible to the proc macro code generation. +At the moment that is not possible due to there is no way to evaluate the actual type behind the type token that is visible to the proc macro code generation. This might be possible in future if a global alias registry can be implemented. Here is an issue related to the topic [#766](https://github.com/juhaku/utoipa/issues/766). ## License diff --git a/utoipa-gen/src/lib.rs b/utoipa-gen/src/lib.rs index e6f0894c..ff6eaf59 100644 --- a/utoipa-gen/src/lib.rs +++ b/utoipa-gen/src/lib.rs @@ -352,7 +352,7 @@ use self::{ /// /// # Generic schemas with aliases /// -/// Schemas can also be generic which allows reusing types. This enables certain behaviour patters +/// Schemas can also be generic which allows reusing types. This enables certain behaviour patterns /// where super type declares common code for type aliases. /// /// In this example we have common `Status` type which accepts one generic type. It is then defined @@ -703,7 +703,7 @@ pub fn derive_to_schema(input: TokenStream) -> TokenStream { /// With _`inline(...)`_ the schema will be inlined instead of a referenced which is the default for /// [`ToSchema`][to_schema] types. _`ref("./external.json")`_ can be used to reference external /// json file for body schema. **Note!** Utoipa does **not** guarantee that free form _`ref`_ is accessbile via -/// OpenAPI doc or Swagger UI, users are eligible to make these guarantees. +/// OpenAPI doc or Swagger UI, users are responsible for making these guarantees. /// /// **Advanced format definition by `request_body(...)`** /// * `content = ...` Can be _`content = Type`_, _`content = inline(Type)`_ or _`content = ref("...")`_. The @@ -711,8 +711,8 @@ pub fn derive_to_schema(input: TokenStream) -> TokenStream { /// or Map etc. With _`inline(...)`_ the schema will be inlined instead of a referenced /// which is the default for [`ToSchema`][to_schema] types. _`ref("./external.json")`_ /// can be used to reference external json file for body schema. **Note!** Utoipa does **not** guarantee -/// that free form _`ref`_ is accessible via OpenAPI doc or Swagger UI, users are eligible -/// to make these guarantees. +/// that free form _`ref`_ is accessible via OpenAPI doc or Swagger UI, users are responsible for making +/// these guarantees. /// /// * `description = "..."` Define the description for the request body object as str. /// @@ -751,8 +751,8 @@ pub fn derive_to_schema(input: TokenStream) -> TokenStream { /// With _`inline(...)`_ the schema will be inlined instead of a referenced which is the default for /// [`ToSchema`][to_schema] types. _`ref("./external.json")`_ /// can be used to reference external json file for body schema. **Note!** Utoipa does **not** guarantee -/// that free form _`ref`_ is accessible via OpenAPI doc or Swagger UI, users are eligible -/// to make these guarantees. +/// that free form _`ref`_ is accessible via OpenAPI doc or Swagger UI, users are responsible for making +/// these guarantees. /// /// * `content_type = "..." | content_type = [...]` Can be used to override the default behavior of auto resolving the content type /// from the `body` attribute. If defined the value should be valid content type such as @@ -1267,7 +1267,7 @@ pub fn derive_to_schema(input: TokenStream) -> TokenStream { /// ```` /// /// _**Example with multiple examples on single response.**_ -///```rust +/// ```rust /// # #[derive(serde::Serialize, serde::Deserialize)] /// # struct User { /// # name: String @@ -1288,7 +1288,7 @@ pub fn derive_to_schema(input: TokenStream) -> TokenStream { /// fn get_user() -> User { /// User {name: "John".to_string()} /// } -///``` +/// ``` /// /// [in_enum]: openapi/path/enum.ParameterIn.html /// [path]: trait.Path.html @@ -1458,8 +1458,8 @@ pub fn path(attr: TokenStream, item: TokenStream) -> TokenStream { /// * `enum_values(...)` Define list of possible values for the variable. Values must be /// literal strings. /// -/// _**Example server variable definition.**_ -/// ```text +/// _**Example server variable definition.**_ +/// ```text /// ("username" = (default = "demo", description = "Default username for API")), /// ("port" = (enum_values("8080", "5000", "4545"))) /// ``` @@ -1513,7 +1513,7 @@ pub fn path(attr: TokenStream, item: TokenStream) -> TokenStream { /// ``` /// /// _**Define servers to OpenApi.**_ -///```rust +/// ```rust /// # use utoipa::OpenApi; /// #[derive(OpenApi)] /// #[openapi( @@ -1528,7 +1528,7 @@ pub fn path(attr: TokenStream, item: TokenStream) -> TokenStream { /// ) /// )] /// struct ApiDoc; -///``` +/// ``` /// /// _**Define info attribute values used to override auto generated ones from Cargo environment /// variables.**_ @@ -1690,9 +1690,9 @@ pub fn openapi(input: TokenStream) -> TokenStream { /// an open value as a string. By default the format is derived from the type of the property /// according OpenApi spec. /// -/// * `write_only` Defines property is only used in **write** operations *POST,PUT,PATCH* but not in *GET* +/// * `write_only` Defines property is only used in **write** operations *POST,PUT,PATCH* but not in *GET*. /// -/// * `read_only` Defines property is only used in **read** operations *GET* but not in *POST,PUT,PATCH* +/// * `read_only` Defines property is only used in **read** operations *GET* but not in *POST,PUT,PATCH*. /// /// * `xml(...)` Can be used to define [`Xml`][xml] object properties applicable to named fields. /// See configuration options at xml attributes of [`ToSchema`][to_schema_xml] @@ -1965,7 +1965,7 @@ pub fn into_params(input: TokenStream) -> TokenStream { #[proc_macro_error] #[proc_macro_derive(ToResponse, attributes(response, content, to_schema))] -/// Generate reusable OpenAPI response what can be used +/// Generate reusable OpenAPI response that can be used /// in [`utoipa::path`][path] or in [`OpenApi`][openapi]. /// /// This is `#[derive]` implementation for [`ToResponse`][to_response] trait. diff --git a/utoipa-rapidoc/src/lib.rs b/utoipa-rapidoc/src/lib.rs index 2b5cbe8f..6fddcd25 100644 --- a/utoipa-rapidoc/src/lib.rs +++ b/utoipa-rapidoc/src/lib.rs @@ -137,7 +137,7 @@ const DEFAULT_HTML: &str = include_str!("../res/rapidoc.html"); /// Is [RapiDoc][rapidoc] UI. /// -/// This is an antry point for serving [RapiDoc][rapidoc] via predefined framework integration or +/// This is an entry point for serving [RapiDoc][rapidoc] via predefined framework integration or /// in standalone fashion by calling [`RapiDoc::to_html`] within custom HTTP handler handles /// serving the [RapiDoc][rapidoc] UI. See more at [running standalone][standalone] /// diff --git a/utoipa-redoc/src/lib.rs b/utoipa-redoc/src/lib.rs index d57b7d38..151c6d2c 100644 --- a/utoipa-redoc/src/lib.rs +++ b/utoipa-redoc/src/lib.rs @@ -210,7 +210,7 @@ pub trait Servable<'u, 's, S> where S: Spec, { - /// Consruct a new [`Servable`] instance of _`openapi`_ with given _`url`_. + /// Construct a new [`Servable`] instance of _`openapi`_ with given _`url`_. /// /// * **url** Must point to location where the [`Servable`] is served. /// * **openapi** Is [`Spec`] that is served via this [`Servable`] from the _**url**_. @@ -218,7 +218,7 @@ where where 'u: 's; - /// Consruct a new [`Servable`] instance of _`openapi`_ with given _`url`_ and _`config`_. + /// Construct a new [`Servable`] instance of _`openapi`_ with given _`url`_ and _`config`_. /// /// * **url** Must point to location where the [`Servable`] is served. /// * **openapi** Is [`Spec`] that is served via this [`Servable`] from the _**url**_. @@ -303,7 +303,7 @@ impl<'s, 'u, S: Spec> Redoc<'s, 'u, S> { } } - /// Override the [ default HTML template][redoc_html_quickstart] with new one. See + /// Override the [default HTML template][redoc_html_quickstart] with new one. See /// [customization] for more details. /// /// [redoc_html_quickstart]: @@ -339,7 +339,7 @@ impl<'s, 'u, S: Spec> Redoc<'s, 'u, S> { /// Trait defines OpenAPI spec resource types supported by [`Redoc`]. /// -/// By deafult this trait is implemented for [`utoipa::openapi::OpenApi`], [`String`], [`&str`] and +/// By default this trait is implemented for [`utoipa::openapi::OpenApi`], [`String`], [`&str`] and /// [`serde_json::Value`]. /// /// * **OpenApi** implementation allows using utoipa's OpenApi struct as a OpenAPI spec resource @@ -352,7 +352,7 @@ impl<'s, 'u, S: Spec> Redoc<'s, 'u, S> { /// # Examples /// /// _**Use [`Redoc`] to serve utoipa's OpenApi.**_ -///```no_run +/// ```no_run /// # use utoipa_redoc::Redoc; /// # use utoipa::openapi::OpenApiBuilder; /// # @@ -388,7 +388,7 @@ impl Spec for Value {} /// config. The [`Config`] must be able to load and serialize valid JSON. /// /// * **EmptyConfig** is the default config and serializes to empty JSON object _`{}`_. -/// * **FileConfig** Allows [`Redoc`] to be configred via user defined file which serializes to +/// * **FileConfig** Allows [`Redoc`] to be configured via user defined file which serializes to /// JSON. /// * **FnOnce** closure config allows inlining JSON serializable config directly to [`Redoc`] /// declaration. @@ -430,7 +430,7 @@ impl Spec for Value {} /// [redoc]: /// [redoc_config]: pub trait Config { - /// Implementor must implement the logic which loads the configuration of choice and coverts it + /// Implementor must implement the logic which loads the configuration of choice and converts it /// to serde's [`serde_json::Value`]. fn load(self) -> Value; } @@ -441,11 +441,11 @@ impl S> Config for F { } } -/// Makes [`Redoc`] to load it's configuration from a user defined file. +/// Makes [`Redoc`] load it's configuration from a user defined file. /// /// The config file must be defined via _**`UTOIPA_REDOC_CONFIG_FILE`**_ env variable for your /// application. It can either be defined in runtime before the [`Redoc`] declaration or before -/// application starup or at compile time via `build.rs` file. +/// application startup or at compile time via `build.rs` file. /// /// The file must be located relative to your application runtime directory. /// diff --git a/utoipa-swagger-ui/src/lib.rs b/utoipa-swagger-ui/src/lib.rs index 25f57932..1ad06339 100644 --- a/utoipa-swagger-ui/src/lib.rs +++ b/utoipa-swagger-ui/src/lib.rs @@ -124,7 +124,7 @@ use utoipa::openapi::OpenApi; #[folder = "$UTOIPA_SWAGGER_DIR/$UTOIPA_SWAGGER_UI_VERSION/dist/"] struct SwaggerUiDist; -/// Entry point for serving Swagger UI and api docs in application. It uses provides +/// Entry point for serving Swagger UI and api docs in application. It provides /// builder style chainable configuration methods for configuring api doc urls. /// /// # Examples @@ -276,7 +276,7 @@ impl SwaggerUi { /// # Examples /// /// Add external API doc to the [`SwaggerUi`]. - ///```rust + /// ```rust /// # use utoipa_swagger_ui::{SwaggerUi, Url}; /// # use utoipa::OpenApi; /// # use serde_json::json; @@ -284,7 +284,7 @@ impl SwaggerUi { /// /// let swagger = SwaggerUi::new("/swagger-ui/{_:.*}") /// .external_url_unchecked("/api-docs/openapi.json", external_openapi); - ///``` + /// ``` pub fn external_url_unchecked>>( mut self, url: U, @@ -308,7 +308,7 @@ impl SwaggerUi { /// # Examples /// /// Add external API docs to the [`SwaggerUi`]. - ///```rust + /// ```rust /// # use utoipa_swagger_ui::{SwaggerUi, Url}; /// # use utoipa::OpenApi; /// # use serde_json::json; @@ -320,7 +320,7 @@ impl SwaggerUi { /// ("/api-docs/openapi.json", external_openapi), /// ("/api-docs/openapi2.json", external_openapi2) /// ]); - ///``` + /// ``` pub fn external_urls_from_iter_unchecked< I: IntoIterator, U: Into>, @@ -486,13 +486,13 @@ const SWAGGER_BASE_LAYOUT: &str = "BaseLayout"; /// /// # Examples /// -/// In simple case create config directly from url that points to the api doc json. +/// In simple case, create config directly from url that points to the api doc json. /// ```rust /// # use utoipa_swagger_ui::Config; /// let config = Config::from("/api-doc.json"); /// ``` /// -/// If there is multiple api docs to serve config can be also directly created with [`Config::new`] +/// If there is multiple api docs to serve config, the [`Config`] can be also be directly created with [`Config::new`] /// ```rust /// # use utoipa_swagger_ui::Config; /// let config = Config::new(["/api-docs/openapi1.json", "/api-docs/openapi2.json"]); @@ -632,7 +632,7 @@ pub struct Config<'a> { #[serde(skip)] oauth: Option, - /// The layout of Swagger UI uses, default is `"StandaloneLayout"` + /// The layout of Swagger UI uses, default is `"StandaloneLayout"`. layout: &'a str, } diff --git a/utoipa-swagger-ui/src/oauth.rs b/utoipa-swagger-ui/src/oauth.rs index c98380ea..cb206872 100644 --- a/utoipa-swagger-ui/src/oauth.rs +++ b/utoipa-swagger-ui/src/oauth.rs @@ -50,7 +50,7 @@ pub struct Config { pub scopes: Option>, /// oauth additional_query_string_params the Swagger UI is using for auth flow. - /// [`HashMap`] of additional query parameters added to authorizationUrl and tokenUrl + /// [`HashMap`] of additional query parameters added to authorizationUrl and tokenUrl. #[serde(skip_serializing_if = "Option::is_none")] pub additional_query_string_params: Option>, @@ -58,14 +58,14 @@ pub struct Config { /// Only activated for the accessCode flow. During the authorization_code request to the tokenUrl, /// pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme /// (Authorization header with Basic base64encode(client_id + client_secret)). - /// The default is false + /// The default is false. #[serde(skip_serializing_if = "Option::is_none")] pub use_basic_authentication_with_access_code_grant: Option, /// oauth use_pkce_with_authorization_code_grant the Swagger UI is using for auth flow. /// Only applies to authorizationCode flows. [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636) /// brings enhanced security for OAuth public clients. - /// The default is false + /// The default is false. #[serde(skip_serializing_if = "Option::is_none")] pub use_pkce_with_authorization_code_grant: Option, } @@ -196,7 +196,7 @@ impl Config { /// Add additional_query_string_params into [`Config`]. /// /// Method takes one argument which exposes the additional_query_string_params to the user. - /// [`HashMap`] of additional query parameters added to authorizationUrl and tokenUrl + /// [`HashMap`] of additional query parameters added to authorizationUrl and tokenUrl. /// /// # Examples /// @@ -221,7 +221,7 @@ impl Config { /// Only activated for the accessCode flow. During the authorization_code request to the tokenUrl, /// pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme /// (Authorization header with Basic base64encode(client_id + client_secret)). - /// The default is false + /// The default is false. /// /// # Examples /// @@ -245,7 +245,7 @@ impl Config { /// Method takes one argument which exposes the use_pkce_with_authorization_code_grant to the user. /// Only applies to authorizationCode flows. [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636) /// brings enhanced security for OAuth public clients. - /// The default is false + /// The default is false. /// /// # Examples /// diff --git a/utoipa/src/lib.rs b/utoipa/src/lib.rs index ef00ba33..fc48251b 100644 --- a/utoipa/src/lib.rs +++ b/utoipa/src/lib.rs @@ -291,7 +291,7 @@ pub use utoipa_gen::*; /// implementation will by default use the Cargo environment variables to set defaults for *application name, /// version, application description, license, author name & email*. /// -///```rust +/// ```rust /// struct OpenApiDoc; /// /// impl utoipa::OpenApi for OpenApiDoc { diff --git a/utoipa/src/openapi/info.rs b/utoipa/src/openapi/info.rs index a4b3d5df..3ba4a1ff 100644 --- a/utoipa/src/openapi/info.rs +++ b/utoipa/src/openapi/info.rs @@ -69,7 +69,7 @@ builder! { /// Document version typically the API version. pub version: String, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } @@ -197,7 +197,7 @@ builder! { #[cfg_attr(feature = "debug", derive(Debug))] #[serde(rename_all = "camelCase")] pub struct License { - /// Name of the license used e.g MIT or Apache-2.0 + /// Name of the license used e.g MIT or Apache-2.0. pub name: String, /// Optional url pointing to the license. diff --git a/utoipa/src/openapi/path.rs b/utoipa/src/openapi/path.rs index c81acc4f..17b6f6d4 100644 --- a/utoipa/src/openapi/path.rs +++ b/utoipa/src/openapi/path.rs @@ -35,7 +35,7 @@ builder! { /// api endpoints. pub paths: PathsMap, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } @@ -145,7 +145,7 @@ builder! { #[serde(flatten)] pub operations: PathsMap, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } @@ -314,7 +314,7 @@ builder! { #[serde(skip_serializing_if = "Option::is_none")] pub servers: Option>, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } @@ -513,12 +513,12 @@ builder! { /// /// With explode _`false`_: /// ```text - ///color=blue,black,brown + /// color=blue,black,brown /// ``` /// /// With explode _`true`_: /// ```text - ///color=blue&color=black&color=brown + /// color=blue&color=black&color=brown /// ``` #[serde(skip_serializing_if = "Option::is_none")] pub explode: Option, @@ -534,7 +534,7 @@ builder! { #[serde(skip_serializing_if = "Option::is_none")] example: Option, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } diff --git a/utoipa/src/openapi/response.rs b/utoipa/src/openapi/response.rs index a75eb183..7b51ede8 100644 --- a/utoipa/src/openapi/response.rs +++ b/utoipa/src/openapi/response.rs @@ -119,7 +119,7 @@ builder! { #[serde(skip_serializing_if = "IndexMap::is_empty", default)] pub content: IndexMap, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } diff --git a/utoipa/src/openapi/schema.rs b/utoipa/src/openapi/schema.rs index 53d3c76a..e8f9f180 100644 --- a/utoipa/src/openapi/schema.rs +++ b/utoipa/src/openapi/schema.rs @@ -88,7 +88,7 @@ impl Components { ..Default::default() } } - /// Add [`SecurityScheme`] to [`Components`] + /// Add [`SecurityScheme`] to [`Components`]. /// /// Accepts two arguments where first is the name of the [`SecurityScheme`]. This is later when /// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the [`SecurityScheme`]. @@ -382,7 +382,7 @@ impl OneOf { } impl OneOfBuilder { - /// Adds a given [`Schema`] to [`OneOf`] [Composite Object][composite] + /// Adds a given [`Schema`] to [`OneOf`] [Composite Object][composite]. /// /// [composite]: https://spec.openapis.org/oas/latest.html#components-object pub fn item>>(mut self, component: I) -> Self { @@ -510,7 +510,7 @@ impl AllOf { } impl AllOfBuilder { - /// Adds a given [`Schema`] to [`AllOf`] [Composite Object][composite] + /// Adds a given [`Schema`] to [`AllOf`] [Composite Object][composite]. /// /// [composite]: https://spec.openapis.org/oas/latest.html#components-object pub fn item>>(mut self, component: I) -> Self { @@ -634,7 +634,7 @@ impl AnyOf { } impl AnyOfBuilder { - /// Adds a given [`Schema`] to [`AnyOf`] [Composite Object][composite] + /// Adds a given [`Schema`] to [`AnyOf`] [Composite Object][composite]. /// /// [composite]: https://spec.openapis.org/oas/latest.html#components-object pub fn item>>(mut self, component: I) -> Self { @@ -725,7 +725,7 @@ builder! { #[serde(skip_serializing_if = "Option::is_none")] pub default: Option, - /// Enum variants of fields that can be represented as `unit` type `enums` + /// Enum variants of fields that can be represented as `unit` type `enums`. #[serde(rename = "enum", skip_serializing_if = "Option::is_none")] pub enum_values: Option>, @@ -1151,7 +1151,7 @@ builder! { #[cfg_attr(feature = "debug", derive(Debug))] #[serde(rename_all = "camelCase")] pub struct Array { - /// Type will always be [`SchemaType::Array`] + /// Type will always be [`SchemaType::Array`]. #[serde(rename = "type")] pub schema_type: SchemaType, diff --git a/utoipa/src/openapi/security.rs b/utoipa/src/openapi/security.rs index cc17fd99..dabf74b8 100644 --- a/utoipa/src/openapi/security.rs +++ b/utoipa/src/openapi/security.rs @@ -35,7 +35,7 @@ pub struct SecurityRequirement { } impl SecurityRequirement { - /// Construct a new [`SecurityRequirement`] + /// Construct a new [`SecurityRequirement`]. /// /// Accepts name for the security requirement which must match to the name of available [`SecurityScheme`]. /// Second parameter is [`IntoIterator`] of [`Into`] scopes needed by the [`SecurityRequirement`]. @@ -298,7 +298,7 @@ impl Default for HttpAuthScheme { } } -/// Open id connect [`SecurityScheme`] +/// Open id connect [`SecurityScheme`]. #[non_exhaustive] #[derive(Serialize, Deserialize, Clone, PartialEq, Eq)] #[serde(rename_all = "camelCase")] @@ -357,7 +357,7 @@ pub struct OAuth2 { #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } @@ -450,7 +450,6 @@ impl OAuth2 { /// [`OAuth2`] flow configuration object. /// -/// /// See more details at . #[derive(Serialize, Deserialize, Clone, PartialEq, Eq)] #[serde(untagged)] diff --git a/utoipa/src/openapi/tag.rs b/utoipa/src/openapi/tag.rs index d2ee6a8f..3607c845 100644 --- a/utoipa/src/openapi/tag.rs +++ b/utoipa/src/openapi/tag.rs @@ -31,7 +31,7 @@ builder! { #[serde(skip_serializing_if = "Option::is_none")] pub external_docs: Option, - /// Optional extensions "x-something" + /// Optional extensions "x-something". #[serde(skip_serializing_if = "Option::is_none", flatten)] pub extensions: Option>, } diff --git a/utoipa/src/openapi/xml.rs b/utoipa/src/openapi/xml.rs index 45b233d9..8024f330 100644 --- a/utoipa/src/openapi/xml.rs +++ b/utoipa/src/openapi/xml.rs @@ -87,14 +87,14 @@ impl XmlBuilder { set_value!(self prefix prefix.map(|prefix| prefix.into())) } - /// Mark [`Xml`] object as attribute. See [`Xml::attribute`] + /// Mark [`Xml`] object as attribute. See [`Xml::attribute`]. /// /// Builder style chainable consuming add attribute method. pub fn attribute(mut self, attribute: Option) -> Self { set_value!(self attribute attribute) } - /// Mark [`Xml`] object wrapped. See [`Xml::wrapped`] + /// Mark [`Xml`] object wrapped. See [`Xml::wrapped`]. /// /// Builder style chainable consuming add wrapped method. pub fn wrapped(mut self, wrapped: Option) -> Self {