feat: add openapi attribute to token exchange endpoint

src/app.rs

@@ -1,8 +1,8 @@
 use crate::config::Config;
 use crate::handlers::__path_introspect;
 use crate::handlers::__path_token;
+use crate::handlers::__path_token_exchange;
 use crate::handlers::{introspect, token, token_exchange, HandlerState};
-use axum::routing::post;
 use axum::Router;
 use log::info;
 use tokio::net::TcpListener;
@@ -47,8 +47,8 @@ impl App {
         #[allow(unused)]
         let (router, openapi) = OpenApiRouter::with_openapi(ApiDoc::openapi())
             .routes(routes!(token))
+            .routes(routes!(token_exchange))
             .routes(routes!(introspect))
-            .route("/token/exchange", post(token_exchange))
             .with_state(state)
             .split_for_parts();
 

src/handlers.rs

@@ -28,7 +28,7 @@ use tokio::sync::RwLock;
             (TokenRequest = "application/json"),
             (TokenRequest = "application/x-www-form-urlencoded"),
         ),
-        description = "Token request"
+        description = "Request a machine-to-machine token for a given `target`."
     ),
     responses(
         (status = OK, description = "Success", body = TokenResponse, content_type = "application/json"),
@@ -47,7 +47,22 @@ pub async fn token(
     }
 }
 
-/// In practice, you need to call this endpoint to speak with other backend applications.
+#[utoipa::path(
+    post,
+    path = "/token/exchange",
+    request_body(
+        content(
+            (TokenExchangeRequest = "application/json"),
+            (TokenExchangeRequest = "application/x-www-form-urlencoded"),
+        ),
+        description = "Exchange a user token for a new token, scoped to the given `target`. The new token contains the user context that allows your application to act on behalf of the user"
+    ),
+    responses(
+        (status = OK, description = "Success", body = TokenResponse, content_type = "application/json"),
+        (status = BAD_REQUEST, description = "Bad request", body = ErrorResponse, content_type = "application/json"),
+        (status = INTERNAL_SERVER_ERROR, description = "Server error", body = ErrorResponse, content_type = "application/json"),
+    )
+)]
 #[axum::debug_handler]
 pub async fn token_exchange(
     State(state): State<HandlerState>,
@@ -68,7 +83,7 @@ pub async fn token_exchange(
             (IntrospectRequest = "application/json"),
             (IntrospectRequest = "application/x-www-form-urlencoded"),
         ),
-        description = "Introspection request"
+        description = "Introspect a token. This validates the token and returns its claims. The `active` field indicates whether the token is valid or not."
     ),
     responses(
         (status = OK, description = "Success", body = HashMap<String, Value>, content_type = "application/json"),

src/identity_provider.rs

@@ -19,6 +19,7 @@ use utoipa::ToSchema;
 pub struct TokenResponse {
     pub access_token: String,
     pub token_type: TokenType,
+    /// Token expiry in seconds. Useful for caching purposes.
     #[serde(rename = "expires_in")]
     pub expires_in_seconds: usize,
 }
@@ -105,7 +106,7 @@ impl From<OAuthErrorCode> for StatusCode {
     }
 }
 
-/// Identity provider for use with token fetch, exchange and validation.
+/// Supported identity providers for use with token fetch, exchange and introspection.
 #[derive(Deserialize, Serialize, ToSchema, Clone, Debug)]
 pub enum IdentityProvider {
     #[serde(rename = "azuread")]
@@ -135,7 +136,9 @@ pub struct TokenExchangeRequest {
     pub target: String,
     pub identity_provider: IdentityProvider,
 
-    /// The token you already have, usually from a previous request to `/token`.
+    /// The token that contains the user's context.
+    ///
+    /// Usually found in the `Authorization` header in requests to your application.
     pub user_token: String,
 }