Skip to content

Improve OpenAPI documentation for session API #10741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 3, 2025
Merged

Improve OpenAPI documentation for session API #10741

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 16 additions & 29 deletions src/controllers/session.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
use axum::Json;
use axum::extract::{FromRequestParts, Query};
use axum_extra::json;
use axum_extra::response::ErasedJson;
use diesel::prelude::*;
use diesel_async::scoped_futures::ScopedFutureExt;
use diesel_async::{AsyncConnection, AsyncPgConnection, RunQueryDsl};
Expand All @@ -20,28 +18,30 @@ use crate::views::EncodableMe;
use crates_io_github::GithubUser;
use crates_io_session::SessionExtension;

#[derive(Debug, Serialize, utoipa::ToSchema)]
pub struct BeginResponse {
#[schema(
example = "https://github.com/login/oauth/authorize?client_id=...&state=...&scope=read%3Aorg"
)]
pub url: String,

#[schema(example = "b84a63c4ea3fcb4ac84")]
pub state: String,
}

/// Begin authentication flow.
///
/// This route will return an authorization URL for the GitHub OAuth flow including the crates.io
/// `client_id` and a randomly generated `state` secret.
///
/// see <https://developer.github.com/v3/oauth/#redirect-users-to-request-github-access>
///
/// ## Response Body Example
///
/// ```json
/// {
/// "state": "b84a63c4ea3fcb4ac84",
/// "url": "https://github.com/login/oauth/authorize?client_id=...&state=...&scope=read%3Aorg"
/// }
/// ```
#[utoipa::path(
get,
path = "/api/private/session/begin",
tag = "session",
responses((status = 200, description = "Successful Response")),
responses((status = 200, description = "Successful Response", body = inline(BeginResponse))),
)]
pub async fn begin_session(app: AppState, session: SessionExtension) -> ErasedJson {
pub async fn begin_session(app: AppState, session: SessionExtension) -> Json<BeginResponse> {
let (url, state) = app
.github_oauth
.authorize_url(oauth2::CsrfToken::new_random)
Expand All @@ -51,7 +51,8 @@ pub async fn begin_session(app: AppState, session: SessionExtension) -> ErasedJs
let state = state.secret().to_string();
session.insert("github_oauth_state".to_string(), state.clone());

json!({ "url": url.to_string(), "state": state })
let url = url.to_string();
Json(BeginResponse { url, state })
}

#[derive(Clone, Debug, Deserialize, FromRequestParts)]
Expand All @@ -74,25 +75,11 @@ pub struct AuthorizeQuery {
///
/// - `code` – temporary code received from the GitHub API **(Required)**
/// - `state` – state parameter received from the GitHub API **(Required)**
///
/// ## Response Body Example
///
/// ```json
/// {
/// "user": {
/// "email": "[email protected]",
/// "name": "Foo Bar",
/// "login": "foobar",
/// "avatar": "https://avatars.githubusercontent.com/u/1234",
/// "url": null
/// }
/// }
/// ```
#[utoipa::path(
get,
path = "/api/private/session/authorize",
tag = "session",
responses((status = 200, description = "Successful Response")),
responses((status = 200, description = "Successful Response", body = inline(EncodableMe))),
)]
pub async fn authorize_session(
query: AuthorizeQuery,
Expand Down
71 changes: 69 additions & 2 deletions src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1174,10 +1174,56 @@ expression: response.json()
},
"/api/private/session/authorize": {
"get": {
"description": "This route is called from the GitHub API OAuth flow after the user accepted or rejected\nthe data access permissions. It will check the `state` parameter and then call the GitHub API\nto exchange the temporary `code` for an API token. The API token is returned together with\nthe corresponding user information.\n\nsee <https://developer.github.com/v3/oauth/#github-redirects-back-to-your-site>\n\n## Query Parameters\n\n- `code` – temporary code received from the GitHub API **(Required)**\n- `state` – state parameter received from the GitHub API **(Required)**\n\n## Response Body Example\n\n```json\n{\n \"user\": {\n \"email\": \"[email protected]\",\n \"name\": \"Foo Bar\",\n \"login\": \"foobar\",\n \"avatar\": \"https://avatars.githubusercontent.com/u/1234\",\n \"url\": null\n }\n}\n```",
"description": "This route is called from the GitHub API OAuth flow after the user accepted or rejected\nthe data access permissions. It will check the `state` parameter and then call the GitHub API\nto exchange the temporary `code` for an API token. The API token is returned together with\nthe corresponding user information.\n\nsee <https://developer.github.com/v3/oauth/#github-redirects-back-to-your-site>\n\n## Query Parameters\n\n- `code` – temporary code received from the GitHub API **(Required)**\n- `state` – state parameter received from the GitHub API **(Required)**",
"operationId": "authorize_session",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"owned_crates": {
"description": "The crates that the authenticated user owns.",
"items": {
"properties": {
"email_notifications": {
"deprecated": true,
"type": "boolean"
},
"id": {
"description": "The opaque identifier of the crate.",
"example": 123,
"format": "int32",
"type": "integer"
},
"name": {
"description": "The name of the crate.",
"example": "serde",
"type": "string"
}
},
"required": [
"id",
"name",
"email_notifications"
],
"type": "object"
},
"type": "array"
},
"user": {
"$ref": "#/components/schemas/AuthenticatedUser",
"description": "The authenticated user."
}
},
"required": [
"user",
"owned_crates"
],
"type": "object"
}
}
},
"description": "Successful Response"
}
},
Expand All @@ -1189,10 +1235,31 @@ expression: response.json()
},
"/api/private/session/begin": {
"get": {
"description": "This route will return an authorization URL for the GitHub OAuth flow including the crates.io\n`client_id` and a randomly generated `state` secret.\n\nsee <https://developer.github.com/v3/oauth/#redirect-users-to-request-github-access>\n\n## Response Body Example\n\n```json\n{\n \"state\": \"b84a63c4ea3fcb4ac84\",\n \"url\": \"https://github.com/login/oauth/authorize?client_id=...&state=...&scope=read%3Aorg\"\n}\n```",
"description": "This route will return an authorization URL for the GitHub OAuth flow including the crates.io\n`client_id` and a randomly generated `state` secret.\n\nsee <https://developer.github.com/v3/oauth/#redirect-users-to-request-github-access>",
"operationId": "begin_session",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"state": {
"example": "b84a63c4ea3fcb4ac84",
"type": "string"
},
"url": {
"example": "https://github.com/login/oauth/authorize?client_id=...&state=...&scope=read%3Aorg",
"type": "string"
}
},
"required": [
"url",
"state"
],
"type": "object"
}
}
},
"description": "Successful Response"
}
},
Expand Down