From a7fc6fc0752df5fcb4e694f1cba292ff8172eccc Mon Sep 17 00:00:00 2001 From: ralpha Date: Sun, 3 Dec 2023 23:12:44 +0100 Subject: [PATCH] Added new FAQ question --- README.md | 27 ++++++++++++++++++++ examples/json-web-api/src/main.rs | 2 ++ rocket-okapi/src/lib.rs | 41 +------------------------------ 3 files changed, 30 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 2c5cce60..54fe17dc 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,33 @@ So: - (Rust code (Rocket) --> OpenAPI) == Okapi - (OpenAPI --> Rust code) != Okapi +- **Q: How do I document my endpoints?**
+A: Okapi automatically uses the [Rust Doc Comments](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html) +from most places, this includes: + - Endpoint functions. + - Endpoint function arguments, using [Schemars][Schemars]. Adding documentation for `String` + and other default types is not possible unless used in an other `struct`. See + [this issue for more info](https://github.com/GREsau/okapi/issues/102#issuecomment-1152918141). + - Endpoint function return type, using [Schemars][Schemars]. Same rules apply as arguments. + In case of `Result`, the error codes can be documented, + [see this example](https://github.com/GREsau/okapi/blob/master/examples/custom_schema/src/error.rs). + +Some more info can be provided using the `#[openapi(...)]` derive macro, for more info see: +[OpenApiAttribute](https://github.com/GREsau/okapi/blob/master/rocket-okapi-codegen/src/openapi_attr/mod.rs#L20). + +[Schemars][Schemars] also can be used to provide more info for objects that implement +`#[derive(JsonSchema)]` using the `#[schemars(...)]` and `#[serde(...)]` syntax. +[For more info see `Attrs`](https://github.com/GREsau/schemars/blob/master/schemars_derive/src/attr/mod.rs#L22) + +Documentation can be enhanced in most other places too, but might require custom implementations. +[See our examples for more info](https://github.com/GREsau/okapi/tree/master/examples). + +If the above is not sufficient, you can always create your custom +[`OpenAPI`](https://docs.rs/okapi/latest/okapi/openapi3/struct.OpenApi.html) objects. +This will can then be merged into the final OpenAPI file. +[For more info see this example](https://github.com/GREsau/okapi/blob/master/examples/custom_schema/src/main.rs#L61). +Use this method only if really necessary! (As it might overwrite other generated objects.) + - **Q: My (diesel) database does not implement `OpenApiFromRequest`.**
A: This is because the parameter does not show up in the path, query or body. So this is considered a [Request Guard](https://rocket.rs/v0.5/guide/requests/#request-guards). diff --git a/examples/json-web-api/src/main.rs b/examples/json-web-api/src/main.rs index bca63e2a..47e3b83c 100644 --- a/examples/json-web-api/src/main.rs +++ b/examples/json-web-api/src/main.rs @@ -9,7 +9,9 @@ use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "camelCase")] struct User { + /// A unique user identifier. user_id: u64, + /// The current username of the user. username: String, #[schemars(example = "example_email")] email: Option, diff --git a/rocket-okapi/src/lib.rs b/rocket-okapi/src/lib.rs index 63ef8390..cba9eefe 100644 --- a/rocket-okapi/src/lib.rs +++ b/rocket-okapi/src/lib.rs @@ -72,46 +72,7 @@ //! //! ## FAQ //! -//! - **Q: My (diesel) database does not implement `OpenApiFromRequest`.**
-//! A: This is because the parameter does not show up in the path, query or body. -//! So this is considered a [Request Guard](https://rocket.rs/v0.5/guide/requests/#request-guards). -//! There is a [derive macro](https://github.com/GREsau/okapi/blob/master/examples/secure_request_guard/src/no_auth.rs) -//! for this, but this does not work in combination with the `#[database("...")]` marco. -//! You can solve this my implementing it manually, like this: -//! -//! ```rust, no_run -//! use rocket_okapi::request::{OpenApiFromRequest, RequestHeaderInput}; -//! use rocket_okapi::gen::OpenApiGenerator; -//! use rocket_sync_db_pools::{diesel, database}; -//! -//! #[database("sqlite_logs")] -//! pub struct MyDB(diesel::SqliteConnection); -//! -//! impl<'r> OpenApiFromRequest<'r> for MyDB { -//! fn from_request_input( -//! _gen: &mut OpenApiGenerator, -//! _name: String, -//! _required: bool, -//! ) -> rocket_okapi::Result { -//! Ok(RequestHeaderInput::None) -//! } -//! } -//! ``` -//! - **Q: ... does not implement `JsonSchema`?**
-//! A: The [`JsonSchema`](https://docs.rs/schemars/latest/schemars/trait.JsonSchema.html) implementation -//! is handled by [`Schemars`][Schemars], make sure you enabled the right -//! [feature flags](https://github.com/GREsau/schemars#optional-dependencies) for it. -//! If it is still not implemented open an issue in the `Schemars` repo. -//! -//! -//! - **Q: Can I add custom data to my OpenAPI spec?**
-//! A: Yes, see the [Custom Schema](examples/custom_schema) example. Okapi also has build in functions -//! if you want to merge the [`OpenAPI`](https://docs.rs/okapi/latest/okapi/openapi3/struct.OpenApi.html) -//! objects manually. -//! -//! - More FAQ questions and answers in [README.md](https://github.com/GREsau/okapi#readme). -//! -//! [Schemars]: https://github.com/GREsau/schemars +//! All FAQ questions and answers can be found in [README.md](https://github.com/GREsau/okapi/tree/master#faq). mod error;