Chore improve macros (#44)

* Improve utoipa::path attribute macro * Improve component macro * Improve macro errors * Fix tests and update docs Now macros have consistent better (opinionated) usage style and is similar to already existing once in Rust ecosystem e.g serde.
juhaku · Mar 16, 2022 · c3f7626 · c3f7626
1 parent f2c1489
commit c3f7626
Show file tree

Hide file tree

Showing 22 changed files with 426 additions and 445 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,11 +1,11 @@
 [package]
 name = "utoipa"
-description = "Compile time rest API documentation for Rust"
+description = "Compile time generated OpenAPI documentation for Rust"
 version = "0.1.0-beta7"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
-keywords = ["rest-api", "openapi", "autogenerate", "documentation", "compile-time"]
+keywords = ["rest-api", "openapi", "auto-generate", "documentation", "compile-time"]
 # documentation = ""
 # homepage = ""
 repository = "https://github.com/juhaku/utoipa"

diff --git a/README.md b/README.md
@@ -93,14 +93,14 @@ mod pet_api {
     /// Get pet from database by pet id  
     #[utoipa::path(
         get,
-        path = "/pets/{id}"
-        responses = [
+        path = "/pets/{id}",
+        responses(
             (status = 200, description = "Pet found succesfully", body = Pet),
             (status = 404, description = "Pet was not found")
-        ],
-        params = [
+        ),
+        params(
             ("id" = u64, path, description = "Pet database id to get Pet for"),
-        ]
+        )
     )]
     async fn get_pet_by_id(pet_id: u64) -> Pet {
         Pet {
@@ -117,7 +117,7 @@ Tie the `Component` and the endpoint above to the OpenApi schema with following
 use utoipa::OpenApi;
 
 #[derive(OpenApi)]
-#[openapi(handlers = [pet_api::get_pet_by_id], components = [Pet])]
+#[openapi(handlers(pet_api::get_pet_by_id), components(Pet))]
 struct ApiDoc;
 
 println!("{}", ApiDoc::openapi().to_pretty_json().unwrap());

diff --git a/src/lib.rs b/src/lib.rs
@@ -15,6 +15,12 @@
 //! Long term goal of the library is to be the place to go when OpenAPI documentation is needed in Rust
 //! codebase.
 //!
+//! Utoipa is framework agnostic and could be used together with any web framework or even without one. While
+//! being portable and standalone one of it's key aspects is simple integration with web frameworks.
+//!
+//! Currently utoipa provides simple integration with actix-web framework but is not limited to the actix-web
+//! framework. All functionalities are not restricted to any specific framework.
+//!
 //! # What's up with the word play?
 //!
 //! The name comes from words `utopic` and `api` where `uto` is the first three letters of utopic
@@ -79,14 +85,14 @@
 //!     /// Get pet from database by pet id  
 //!     #[utoipa::path(
 //!         get,
-//!         path = "/pets/{id}"
-//!         responses = [
+//!         path = "/pets/{id}",
+//!         responses(
 //!             (status = 200, description = "Pet found succesfully", body = Pet),
 //!             (status = 404, description = "Pet was not found")
-//!         ],
-//!         params = [
+//!         ),
+//!         params(
 //!             ("id" = u64, path, description = "Pet database id to get Pet for"),
-//!         ]
+//!         )
 //!     )]
 //!     async fn get_pet_by_id(pet_id: u64) -> Pet {
 //!         Pet {
@@ -115,14 +121,14 @@
 //! #     /// Get pet from database by pet id  
 //! #     #[utoipa::path(
 //! #         get,
-//! #         path = "/pets/{id}"
-//! #         responses = [
+//! #         path = "/pets/{id}",
+//! #         responses(
 //! #             (status = 200, description = "Pet found succesfully", body = Pet),
 //! #             (status = 404, description = "Pet was not found")
-//! #         ],
-//! #         params = [
+//! #         ),
+//! #         params(
 //! #             ("id" = u64, path, description = "Pet database id to get Pet for"),
-//! #         ]
+//! #         )
 //! #     )]
 //! #     async fn get_pet_by_id(pet_id: u64) -> Pet {
 //! #         Pet {
@@ -289,14 +295,14 @@ pub trait Component {
 /// /// Get pet from database by pet database id  
 /// #[utoipa::path(
 ///     get,
-///     path = "/pets/{id}"
-///     responses = [
+///     path = "/pets/{id}",
+///     responses(
 ///         (status = 200, description = "Pet found succesfully", body = Pet),
 ///         (status = 404, description = "Pet was not found")
-///     ],
-///     params = [
+///     ),
+///     params(
 ///         ("id" = u64, path, description = "Pet database id to get Pet for"),
-///     ]
+///     )
 /// )]
 /// async fn get_pet_by_id(pet_id: u64) -> Pet {
 ///     Pet {

diff --git a/tests/path_derive.rs b/tests/path_derive.rs
@@ -31,10 +31,10 @@ macro_rules! test_api_fn {
                 $operation,
                 $( operation_id = $operation_id, )*
                 path = $path,
-                responses = [
+                responses(
                     (status = 200, description = "success response")
-                ],
-                $( params = $params, )*
+                ),
+                $( params $params, )*
                 $( tag = $tag, )*
             )]
             #[allow(unused)]
@@ -90,7 +90,7 @@ test_api_fn! {
     module: derive_path_with_all_info,
     operation: post,
     path: "/foo/bar/{id}",
-    params: [("id", description = "Foo bar id")],
+    params: (("id", description = "Foo bar id")),
     operation_id: "foo_bar_id",
     tag: "custom_tag";
     /// This is test operation description
@@ -152,13 +152,13 @@ fn derive_path_with_defaults_success() {
 #[utoipa::path(
     get,
     path = "/foo/{id}",
-    responses = [
+    responses(
         (status = 200, description = "success response")
-    ],
-    params = [
+    ),
+    params(
         ("id" = u64, description = "Foo database id"),
         ("since" = Option<String>, query, description = "Datetime since foo is updated")
-    ]
+    )
 )]
 #[allow(unused)]
 async fn get_foos_by_id_since() -> String {
@@ -204,9 +204,9 @@ fn derive_path_with_security_requirements() {
     #[utoipa::path(
         get,
         path = "/items",
-        responses = [
+        responses(
             (status = 200, description = "success response")
-        ],
+        ),
         security(
             (),
             ("api_oauth" = ["read:items", "edit:items"]),

diff --git a/tests/path_derive_actix.rs b/tests/path_derive_actix.rs
@@ -14,12 +14,12 @@ mod mod_derive_path_actix {
     ///
     /// Get foo by id long description
     #[utoipa::path(
-        responses = [
+        responses(
             (status = 200, description = "success response")
-        ],
-        params = [
+        ),
+        params(
             ("id", description = "Foo id"),
-        ]
+        )
     )]
     #[get("/foo/{id}")]
     #[allow(unused)]
@@ -57,12 +57,12 @@ mod mod_derive_path_unnamed_regex_actix {
     ///
     /// Get foo by id long description
     #[utoipa::path(
-        responses = [
+        responses(
             (status = 200, description = "success"),
-        ],
-        params = [
+        ),
+        params(
             ("arg0", description = "Foo path unnamed regex tail")
-        ]
+        )
     )]
     #[get("/foo/{_:.*}")]
     #[allow(unused)]
@@ -100,12 +100,12 @@ mod mod_derive_path_named_regex_actix {
     ///
     /// Get foo by id long description
     #[utoipa::path(
-        responses = [
+        responses(
             (status = 200, description = "success response")
-        ],
-        params = [
+        ),
+        params(
             ("tail", description = "Foo path named regex tail")
-        ]
+        )
     )]
     #[get("/foo/{tail:.*}")]
     #[allow(unused)]
@@ -143,9 +143,9 @@ macro_rules! test_derive_path_operations {
             use serde_json::json;
 
             #[utoipa::path(
-                responses = [
+                responses(
                     (status = 200, description = "success response")
-                ]
+                )
             )]
             #[$operation("/foo")]
             #[allow(unused)]

diff --git a/tests/path_parameter_derive_actix.rs b/tests/path_parameter_derive_actix.rs
@@ -15,13 +15,13 @@ mod derive_params_multiple_actix {
     #[utoipa::path(
         get,
         path = "/foo/{id}/{digest}",
-        responses = [
+        responses(
             (status = 200, description = "success response")
-        ],
-        params = [
+        ),
+        params(
             ("id", description = "Foo id"),
             ("digest", description = "Digest of foo"),
-        ]
+        )
     )]
     #[allow(unused)]
     async fn get_foo_by_id(web::Path((id, digest)): web::Path<(i32, String)>) -> impl Responder {
@@ -68,13 +68,13 @@ mod derive_parameters_multiple_no_matching_names_actix {
     #[utoipa::path(
         get,
         path = "/foo/{id}/{digest}",
-        responses = [
+        responses(
             (status = 200, description = "success response")
-        ],
-        params = [
+        ),
+        params(
             ("id" = i32, description = "Foo id"),
             ("digest" = String, description = "Digest of foo"),
-        ]
+        )
     )]
     #[allow(unused)]
     async fn get_foo_by_id(info: web::Path<(i32, String)>) -> impl Responder {
@@ -119,9 +119,9 @@ mod derive_params_from_method_args_actix {
     #[utoipa::path(
         get,
         path = "/foo/{id}/{digest}",
-        responses = [
+        responses(
             (status = 200, description = "success response")
-        ],
+        ),
     )]
     #[allow(unused)]
     async fn get_foo_by_id(web::Path((id, digest)): web::Path<(i32, String)>) -> impl Responder {

diff --git a/tests/path_parameter_derive_test.rs b/tests/path_parameter_derive_test.rs
@@ -12,12 +12,12 @@ mod derive_params_all_options {
     #[utoipa::path(
         get,
         path = "/foo/{id}",
-        responses = [
+        responses(
             (status = 200, description = "success"),
-        ],
-        params = [
+        ),
+        params(
             ("id" = i32, path, deprecated, description = "Search foos by ids"),
-        ]
+        )
     )]
     #[allow(unused)]
     async fn get_foo_by_id(id: i32) -> i32 {
@@ -53,12 +53,12 @@ mod derive_params_minimal {
     #[utoipa::path(
         get,
         path = "/foo/{id}",
-        responses = [
+        responses(
             (status = 200, description = "success"),
-        ],
-        params = [
+        ),
+        params(
             ("id" = i32, description = "Search foos by ids"),
-        ]
+        )
     )]
     #[allow(unused)]
     async fn get_foo_by_id(id: i32) -> i32 {
@@ -94,13 +94,13 @@ mod derive_params_multiple {
     #[utoipa::path(
         get,
         path = "/foo/{id}/{digest}",
-        responses = [
+        responses(
             (status = 200, description = "success"),
-        ],
-        params = [
+        ),
+        params(
             ("id" = i32, description = "Foo id"),
             ("digest" = String, description = "Digest of foo"),
-        ]
+        )
     )]
     #[allow(unused)]
     async fn get_foo_by_id(id: i32, digest: String) -> String {
@@ -144,16 +144,16 @@ mod mod_derive_parameters_all_types {
     #[utoipa::path(
         get,
         path = "/foo/{id}",
-        responses = [
+        responses(
             (status = 200, description = "success"),
-        ],
-        params = [
+        ),
+        params(
             ("id" = i32, path, description = "Foo id"),
             ("since" = String, deprecated, query, description = "Datetime since"),
             ("numbers" = Option<[u64]>, query, description = "Foo numbers list"),
             ("token" = String, header, deprecated, description = "Token of foo"),
             ("cookieval" = String, cookie, deprecated, description = "Foo cookie"),
-        ]
+        )
     )]
     #[allow(unused)]
     async fn get_foo_by_id(id: i32) -> i32 {
@@ -220,12 +220,12 @@ mod derive_params_without_args {
     #[utoipa::path(
         get,
         path = "/foo/{id}",
-        responses = [
+        responses(
             (status = 200, description = "success"),
-        ],
-        params = [
+        ),
+        params(
             ("id" = i32, path, description = "Foo id"),
-        ]
+        )
     )]
     #[allow(unused)]
     async fn get_foo_by_id() -> String {