Added new FAQ question

README.md

@@ -50,6 +50,33 @@ So:
   - (Rust code (Rocket) --> OpenAPI) == Okapi
   - (OpenAPI --> Rust code) != Okapi
 
+- **Q: How do I document my endpoints?**<br/>
+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<T, E>`, 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`.**<br/>
 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).

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<String>,

rocket-okapi/src/lib.rs

@@ -72,46 +72,7 @@
 //!
 //! ## FAQ
 //!
-//! - **Q: My (diesel) database does not implement `OpenApiFromRequest`.**<br/>
-//! 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<RequestHeaderInput> {
-//!         Ok(RequestHeaderInput::None)
-//!     }
-//! }
-//! ```
-//! - **Q: ... does not implement `JsonSchema`?**<br/>
-//! 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?**<br/>
-//! 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;