Update OpenAPI documention (#671)

* Update OpenAPI documention

* Format Rust code using rustfmt

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

crates/oapi-macros/src/lib.rs

@@ -59,6 +59,10 @@ pub(crate) use self::{
 };
 pub(crate) use salvo_serde_util::{self as serde_util, RenameRule, SerdeContainer, SerdeValue};
 
+/// Enhanced of [handler][handler] for generate OpenAPI documention, [Read more][more].
+///
+/// [handler]: ../salvo_core/attr.handler.html
+/// [more]: ../salvo_oapi/endpoint/index.html
 #[proc_macro_error]
 #[proc_macro_attribute]
 pub fn endpoint(attr: TokenStream, input: TokenStream) -> TokenStream {
@@ -69,7 +73,10 @@ pub fn endpoint(attr: TokenStream, input: TokenStream) -> TokenStream {
         Err(e) => e.to_compile_error().into(),
     }
 }
-
+/// This is `#[derive]` implementation for [`ToSchema`][to_schema] trait, [Read more][more].
+///
+/// [to_schema]: ../salvo_oapi/trait.ToSchema.html
+/// [more]: ../salvo_oapi/derive.ToSchema.html
 #[proc_macro_error]
 #[proc_macro_derive(ToSchema, attributes(salvo))] //attributes(schema)
 pub fn derive_to_schema(input: TokenStream) -> TokenStream {
@@ -84,6 +91,9 @@ pub fn derive_to_schema(input: TokenStream) -> TokenStream {
     ToSchema::new(&data, &attrs, &ident, &generics).to_token_stream().into()
 }
 
+/// Generate parameters from struct's fields, [Read more][more].
+///
+/// [more]: ../salvo_oapi/derive.ToParameters.html
 #[proc_macro_error]
 #[proc_macro_derive(ToParameters, attributes(salvo))] //attributes(parameter, parameters)
 pub fn derive_to_parameters(input: TokenStream) -> TokenStream {
@@ -105,6 +115,10 @@ pub fn derive_to_parameters(input: TokenStream) -> TokenStream {
     .into()
 }
 
+/// Generate reusable [OpenApi][openapi] response, [Read more][more].
+///
+/// [openapi]: ../salvo_oapi/struct.OpenApi.html
+/// [more]: ../salvo_oapi/derive.ToResponse.html
 #[proc_macro_error]
 #[proc_macro_derive(ToResponse, attributes(salvo))] //attributes(response, content, schema))
 pub fn derive_to_response(input: TokenStream) -> TokenStream {
@@ -119,6 +133,10 @@ pub fn derive_to_response(input: TokenStream) -> TokenStream {
     ToResponse::new(attrs, &data, generics, ident).to_token_stream().into()
 }
 
+/// Generate responses with status codes what can be used in [OpenAPI][openapi], [Read more][more].
+///
+/// [openapi]: ../salvo_oapi/struct.OpenApi.html
+/// [more]: ../salvo_oapi/derive.ToResponses.html
 #[proc_macro_error]
 #[proc_macro_derive(ToResponses, attributes(salvo))] //attributes(response, schema, ref_response, response))
 pub fn to_responses(input: TokenStream) -> TokenStream {

crates/oapi/docs/derive_to_parameters.md

@@ -1,9 +1,8 @@
-Generate [path parameters][path_params] from struct's
-fields.
+Generate parameters from struct's fields.
 
 This is `#[derive]` implementation for [`ToParameters`][to_parameters] trait.
 
-Typically path parameters need to be defined within [`#[salvo_oapi::endpoint(...parameters(...))]`][path_params] section
+Typically path parameters need to be defined within `#[salvo_oapi::endpoint(...parameters(...))]` section
 for the endpoint. But this trait eliminates the need for that when [`struct`][struct]s are used to define parameters.
 Still [`std::primitive`] and [`String`](std::string::String) path parameters or [`tuple`] style path parameters need to be defined
 within `parameters(...)` section if description or other than default configuration need to be given.
@@ -292,7 +291,6 @@ struct Query {
 [known_format]: openapi/schema/enum.KnownFormat.html
 [xml]: openapi/xml/struct.Xml.html
 [to_parameters]: trait.ToParameters.html
-[path_params]: attr.path.html#params-attributes
 [struct]: https://doc.rust-lang.org/std/keyword.struct.html
 [style]: openapi/path/enum.ParameterStyle.html
 [in_enum]: salvo_oapi/openapi/path/enum.ParameterIn.html

crates/oapi/docs/derive_to_response.md

@@ -1,5 +1,4 @@
-Generate reusable OpenAPI response what can be used
-in [`salvo_oapi::endpoint`][path] or in [`OpenApi`][openapi].
+Generate reusable [OpenApi][openapi] response.
 
 This is `#[derive]` implementation for [`ToResponse`][to_response] trait.
 
@@ -205,5 +204,4 @@ _**Create enum response from variants.**_
 
 [to_response]: trait.ToResponse.html
 [primitive]: https://doc.rust-lang.org/std/primitive/index.html
-[path]: attr.path.html
 [openapi]: derive.OpenApi.html

crates/oapi/docs/derive_to_responses.md

@@ -1,5 +1,4 @@
-Generate responses with status codes what
-can be attached to the [`salvo_oapi::endpoint`][path_to_responses].
+Generate responses with status codes what can be used in [`OpenApi`][openapi].
 
 This is `#[derive]` implementation of [`ToResponses`][to_responses] trait. [`derive@ToResponses`]
 can be used to decorate _`structs`_ and _`enums`_ to generate response maps that can be used in
@@ -174,4 +173,5 @@ enum UserResponses {
 [to_schema]: trait.ToSchema.html
 [to_response]: trait.ToResponse.html
 [path_to_responses]: attr.path.html#responses-from-intoresponses
-[primitive]: https://doc.rust-lang.org/std/primitive/index.html
+[primitive]: https://doc.rust-lang.org/std/primitive/index.html
+[openapi]: derive.OpenApi.html

crates/oapi/docs/derive_to_schema.md

@@ -1,5 +1,7 @@
 
-This is `#[derive]` implementation for [`ToSchema`][to_schema] trait. The macro accepts one
+This is `#[derive]` implementation for [`ToSchema`][to_schema] trait. 
+
+The macro accepts one
 `schema`
 attribute optionally which can be used to enhance generated documentation. The attribute can be placed
 at item level or field level in struct and enums. Currently placing this attribute to unnamed field does

crates/oapi/docs/endpoint.md

@@ -1,4 +1,4 @@
-Endpoint attribute macro implements OpenAPI path for the decorated function.
+Enhanced of [handler][handler] for generate OpenAPI documention.
 
 Macro accepts set of attributes that can be used to configure and override default values what are resolved automatically.
 
@@ -438,6 +438,7 @@ async fn get_user() -> Json<User> {
 }
 ```
 
+[handler]: ../salvo_core/attr.handler.html
 [in_enum]: enum.ParameterIn.html
 [path]: trait.Path.html
 [to_schema]: trait.ToSchema.html

crates/oapi/src/endpoint.rs

@@ -141,7 +141,7 @@ impl<'a> EndpointOutRegister for &'a String {
     }
 }
 
-/// A components for all endpoints.
+/// A component for all endpoints.
 #[non_exhaustive]
 pub struct EndpointRegistry {
     /// The type id of the endpoint.

crates/oapi/src/lib.rs

@@ -37,6 +37,7 @@ cfg_feature! {
     pub mod redoc;
 }
 
+#[doc = include_str!("../docs/endpoint.md")]
 pub use salvo_oapi_macros::endpoint;
 pub(crate) use salvo_oapi_macros::schema;
 #[doc = include_str!("../docs/derive_to_parameters.md")]

crates/oapi/src/openapi/components.rs

@@ -51,7 +51,7 @@ impl 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`].
     ///
-    /// [requirement]: ../security/struct.SecurityRequirement.html
+    /// [requirement]: crate::SecurityRequirement
     pub fn add_security_scheme<N: Into<String>, S: Into<SecurityScheme>>(
         mut self,
         name: N,
@@ -67,7 +67,7 @@ impl 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`].
     ///
-    /// [requirement]: ../security/struct.SecurityRequirement.html
+    /// [requirement]: crate::SecurityRequirement
     pub fn extend_security_schemes<I: IntoIterator<Item = (N, S)>, N: Into<String>, S: Into<SecurityScheme>>(
         mut self,
         schemas: I,

crates/oapi/src/openapi/mod.rs

@@ -234,7 +234,7 @@ impl OpenApi {
     /// 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`].
     ///
-    /// [requirement]: ../security/struct.SecurityRequirement.html
+    /// [requirement]: crate::SecurityRequirement
     pub fn add_security_scheme<N: Into<String>, S: Into<SecurityScheme>>(
         mut self,
         name: N,
@@ -252,7 +252,7 @@ impl OpenApi {
     /// 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`].
     ///
-    /// [requirement]: ../security/struct.SecurityRequirement.html
+    /// [requirement]: crate::SecurityRequirement
     pub fn extend_security_schemes<I: IntoIterator<Item = (N, S)>, N: Into<String>, S: Into<SecurityScheme>>(
         mut self,
         schemas: I,