diff --git a/Cargo.toml b/Cargo.toml index 464d2f6f..d36ba9a6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "utoipa" description = "Compile time generated OpenAPI documentation for Rust" -version = "0.1.0-beta7" +version = "0.1.0-rc1" edition = "2021" license = "MIT OR Apache-2.0" readme = "README.md" @@ -24,11 +24,11 @@ json = ["serde_json", "utoipa-gen/json"] [dependencies] serde = { version = "1.0", features = ["derive"] } serde_json = { version = "1.0", optional = true } -utoipa-gen = { version = "0.1.0-beta7", path = "./utoipa-gen" } +utoipa-gen = { version = "0.1.0-rc1", path = "./utoipa-gen" } [dev-dependencies] actix-web = { version = "4" } -paste = "1.0.6" +paste = "1" [workspace] members = [ diff --git a/README.md b/README.md index 52e13a1d..253979ac 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # utoipa - Auto generated OpenAPI documentation [![Utoipa build](https://github.com/juhaku/utoipa/actions/workflows/build.yaml/badge.svg)](https://github.com/juhaku/utoipa/actions/workflows/build.yaml) -[![crates.io](https://img.shields.io/static/v1?label=crates.io&message=0.1.0-beta6&color=orange&logo=rust)](https://crates.io/crates/utoipa/0.1.0-beta6) -[![docs.rs](https://img.shields.io/static/v1?label=docs.rs&message=utoipa&color=blue&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K)](https://docs.rs/utoipa/0.1.0-beta6/utoipa/) +[![crates.io](https://img.shields.io/static/v1?label=crates.io&message=0.1.0-rc1&color=orange&logo=rust)](https://crates.io/crates/utoipa/0.1.0-rc1) +[![docs.rs](https://img.shields.io/static/v1?label=docs.rs&message=utoipa&color=blue&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K)](https://docs.rs/utoipa/0.1.0-rc1/utoipa/) Want to have your API documented with OpenAPI? But you dont want to see the trouble with manual yaml or json tweaking? Would like it to be so easy that it would almost @@ -11,12 +11,12 @@ the most of heavy lifting for you enabling you to focus writing the actual API l documentation. It aims to be *minimal*, *simple* and *fast*. It uses simple proc macros which you can use to annotate your code to have items documented. -Utoipa crate provides autogenerated OpenAPI documentation for Rust REST APIs. It treats +Utoipa crate provides auto generated OpenAPI documentation for Rust REST APIs. It treats code first appoach as a first class citizen and simplifies API documentation by providing simple macros for generating the documentation from your code. It also contains Rust types of OpenAPI spec allowing you to write the OpenAPI spec only using -Rust if autogeneration is not your flavor or does not fit your purpose. +Rust if auto generation is not your flavor or does not fit your purpose. Long term goal of the library is to be the place to go when OpenAPI documentation is needed in Rust codebase. @@ -38,7 +38,7 @@ and the `ipa` is _api_ reversed. * **json** Enables **serde_json** what allow to use json values in OpenAPI specification values. Thus is enabled by default. * **actix_extras** Enhances actix-web intgration with being able to parse some documentation - from actix web macro attributes and types. See the [path attribute macro](https://docs.rs/utoipa/0.1.0-beta6/utoipa/attr.path.html) for more details. + from actix web macro attributes and types. See the [path attribute macro](https://docs.rs/utoipa/0.1.0-rc1/utoipa/attr.path.html) for more details. * **debug** Add extra traits such as debug traits to openapi definitions and elsewhere. ## Install @@ -46,27 +46,28 @@ and the `ipa` is _api_ reversed. Add minimal dependency declaration to Cargo.toml. ``` [dependencies] -utoipa = "0.1.0-beta6" +utoipa = "0.1.0-rc1" ``` To enable more features such as use actix framework extras you could define the dependency as follows. ``` [dependencies] -utoipa = { version = "0.1.0-beta6", features = ["actix_extras"] } +utoipa = { version = "0.1.0-rc1", features = ["actix_extras"] } ``` **Note!** To use `utoipa` together with Swagger UI you can use the [utoipa-swagger-ui](https://docs.rs/utoipa-swagger-ui/) crate. ## Current project status -**This project is currently in active development and not ready for PRODUCTION use!** +Finally in `rc` the API is fairly stable and most of the features are implemented and documented. +While **changes might still occur** before the final **stable** release there should not be any more +massive changes. The expected changes include mainly performance optimisations and fixing +inconsistencies or other minor tweaks and missing features might be included. -The API might change anytime before the first **stable** release while still in pre-release state. +The **stable** release is expected in short future. -The basic features are nearly implemented and the it can handle the OpenApi generation in most typical situations. -There are already prereleases available in crates.io and is still pending the first stable release. Before the -first stable release there are going to be still couple of beta releases and one or few rc releases. +**Use with cauntion!** See https://github.com/juhaku/utoipa/projects for more details about the progress of the project implementation. @@ -211,8 +212,8 @@ This would produce api doc something similar to: * See how to serve OpenAPI doc via Swagger UI check [utoipa-swagger-ui](https://docs.rs/utoipa-swagger-ui/) crate for more details. * Browse to [examples](https://github.com/juhaku/utoipa/tree/master/examples) for more comprehensinve examples. -* Modify generated OpenAPI at runtime check [Modify](https://docs.rs/utoipa/0.1.0-beta6/utoipa/trait.Modify.html) trait for more details. -* More about OpenAPI security in [security documentation](https://docs.rs/utoipa/0.1.0-beta6/utoipa/openapi/security/index.html). +* Modify generated OpenAPI at runtime check [Modify](https://docs.rs/utoipa/0.1.0-rc1/utoipa/trait.Modify.html) trait for more details. +* More about OpenAPI security in [security documentation](https://docs.rs/utoipa/0.1.0-rc1/utoipa/openapi/security/index.html). # License diff --git a/src/lib.rs b/src/lib.rs index b60b4d5a..49bf9414 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -23,8 +23,8 @@ //! //! # What's up with the word play? //! -//! The name comes from words `utopic` and `api` where `uto` is the first three letters of utopic -//! and the `ipa` is api reversed. +//! The name comes from words `utopic` and `api` where `uto` is the first three letters of _utopic_ +//! and the `ipa` is _api_ reversed. //! //! # Features //! diff --git a/utoipa-gen/Cargo.toml b/utoipa-gen/Cargo.toml index cfc61b32..76ac5012 100644 --- a/utoipa-gen/Cargo.toml +++ b/utoipa-gen/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "utoipa-gen" description = "Code generation implementation for utoipa" -version = "0.1.0-beta7" +version = "0.1.0-rc1" edition = "2021" license = "MIT OR Apache-2.0" readme = "README.md" @@ -24,7 +24,6 @@ utoipa = { path = ".." } serde_json = "1" actix-web = { version = "4" } - [features] debug = ["syn/extra-traits"] actix_extras = ["regex", "lazy_static"] diff --git a/utoipa-swagger-ui/Cargo.toml b/utoipa-swagger-ui/Cargo.toml index 9dab244a..62bb6f28 100644 --- a/utoipa-swagger-ui/Cargo.toml +++ b/utoipa-swagger-ui/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "utoipa-swagger-ui" description = "Swagger UI for utoipa" -version = "0.1.0-beta2" +version = "0.1.0-rc1" edition = "2021" license = "MIT OR Apache-2.0" readme = "README.md" @@ -16,7 +16,7 @@ debug = [] rust-embed = { version = "6.3", features = ["interpolate-folder-path"] } mime_guess = { version = "2.0" } actix-web = { version = "4", optional = true } -utoipa = { version = "0.1.0-beta6", path = "..", default-features = false, features = [] } +utoipa = { version = "0.1.0-rc1", path = "..", default-features = false, features = [] } [package.metadata.docs.rs] features = ["actix-web"] diff --git a/utoipa-swagger-ui/README.md b/utoipa-swagger-ui/README.md index 77a4a657..71862acb 100644 --- a/utoipa-swagger-ui/README.md +++ b/utoipa-swagger-ui/README.md @@ -1,8 +1,8 @@ # utoipa-swagger-ui [![Utoipa build](https://github.com/juhaku/utoipa/actions/workflows/build.yaml/badge.svg)](https://github.com/juhaku/utoipa/actions/workflows/build.yaml) -[![crates.io](https://img.shields.io/static/v1?label=crates.io&message=0.1.0-beta1&color=orange&logo=rust)](https://crates.io/crates/utoipa-swagger-ui/0.1.0-beta1) -[![docs.rs](https://img.shields.io/static/v1?label=docs.rs&message=utoipa-swagger-ui&color=blue&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K)](https://docs.rs/utoipa-swagger-ui/0.1.0-beta1/utoipa_swagger_ui/) +[![crates.io](https://img.shields.io/static/v1?label=crates.io&message=0.1.0-rc1&color=orange&logo=rust)](https://crates.io/crates/utoipa-swagger-ui/0.1.0-rc1) +[![docs.rs](https://img.shields.io/static/v1?label=docs.rs&message=utoipa-swagger-ui&color=blue&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K)](https://docs.rs/utoipa-swagger-ui/0.1.0-rc1/utoipa_swagger_ui/) This crate implements necessary boiler plate code to serve Swagger UI via web server. It works as a bridge for serving the OpenAPI documetation created with @@ -10,7 +10,7 @@ works as a bridge for serving the OpenAPI documetation created with **Currently supported frameworks:** -* **actix-web** +* **actix-web** `version >= 4` Serving Swagger UI is framework independant thus `SwaggerUi` and `Url` of this create could be used similarly to serve the Swagger UI in other frameworks as well. @@ -25,13 +25,13 @@ could be used similarly to serve the Swagger UI in other frameworks as well. Use only the raw types without any boiler plate implementation. ```text [dependencies] -utoipa-swagger-ui = "0.1.0.beta1" +utoipa-swagger-ui = "0.1.0.rc1" ``` Enable actix-web framework with Swagger UI you could define the dependency as follows. ```text [dependencies] -utoipa-swagger-ui = { version = "0.1.0.beta1", features = ["actix-web"] } +utoipa-swagger-ui = { version = "0.1.0.rc1", features = ["actix-web"] } ``` **Note!** Also remember that you already have defined `utoipa` dependency in your `Cargo.toml` @@ -44,7 +44,7 @@ HttpServer::new(move || { App::new() .service( SwaggerUi::new("/swagger-ui/{_:.*}") - .with_url("/api-doc/openapi.json", ApiDoc::openapi()), + .url("/api-doc/openapi.json", ApiDoc::openapi()), ) }) .bind(format!("{}:{}", Ipv4Addr::UNSPECIFIED, 8989)).unwrap()