From 385e6b0f8c7c49b9b7f308a27b5c861a94a2d149 Mon Sep 17 00:00:00 2001
From: Klimenty Titov <aclo.create@gmail.com>
Date: Mon, 24 Jun 2024 23:39:47 +0300
Subject: [PATCH] Improved OpenAPI docs (#820)

* oapi: extend security attributes docs

* oapi: fix typo

* oapi: fix checks
---
 crates/oapi/docs/endpoint.md                | 27 +++++++++++++++++++++
 crates/oapi/src/extract/parameter/cookie.rs |  4 +--
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/crates/oapi/docs/endpoint.md b/crates/oapi/docs/endpoint.md
index 004271ea4..08abdaa74 100644
--- a/crates/oapi/docs/endpoint.md
+++ b/crates/oapi/docs/endpoint.md
@@ -41,6 +41,33 @@ fn endpoint() {}
 
 * `security(...)` List of [`SecurityRequirement`][security]s local to the path operation.
 
+# Security Attributes
+
+To configure security requirements, you need to add one or more security schemes when creating an `OpenApi` object,
+as indicated in the example:
+
+```rust
+use salvo_oapi::security::{Http, HttpAuthScheme};
+use salvo_oapi::{OpenApi, SecurityScheme};
+
+#[tokio::main]
+async fn main() {
+    let doc = OpenApi::new("test", "0.1")
+        .add_security_scheme(
+            "bearer",
+            SecurityScheme::Http(Http::new(HttpAuthScheme::Bearer).bearer_format("JSON")));
+}
+```
+
+And, accordingly, when using the `endpoint` macro, specify the scheme:
+
+```rust
+use salvo_oapi::endpoint;
+
+#[endpoint(security(["bearer" = ["bearer"]]))]
+pub async fn authenticated_action() {}
+```
+
 # Request Body Attributes
 
 **Simple format definition by `request_body = ...`**
diff --git a/crates/oapi/src/extract/parameter/cookie.rs b/crates/oapi/src/extract/parameter/cookie.rs
index e7a58a869..a96ba0153 100644
--- a/crates/oapi/src/extract/parameter/cookie.rs
+++ b/crates/oapi/src/extract/parameter/cookie.rs
@@ -28,7 +28,7 @@ impl<T> Deref for CookieParam<T, true> {
     type Target = T;
 
     fn deref(&self) -> &Self::Target {
-        self.0.as_ref().expect("`CookieParam<T, true>` defref get `None`")
+        self.0.as_ref().expect("`CookieParam<T, true>` deref get `None`")
     }
 }
 impl<T> Deref for CookieParam<T, false> {
@@ -41,7 +41,7 @@ impl<T> Deref for CookieParam<T, false> {
 
 impl<T> DerefMut for CookieParam<T, true> {
     fn deref_mut(&mut self) -> &mut Self::Target {
-        self.0.as_mut().expect("`CookieParam<T, true>` defref_mut get `None`")
+        self.0.as_mut().expect("`CookieParam<T, true>` deref_mut get `None`")
     }
 }
 impl<T> DerefMut for CookieParam<T, false> {