Skip to content

Improve OpenAPI description #10521

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 3 commits into from
Feb 7, 2025
Merged

Improve OpenAPI description #10521

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6f2ffa9
OpenAPI: Extend `description` field
Turbo87 Feb 6, 2025
15566be
OpenAPI: Fix `license` field
Turbo87 Feb 6, 2025
6c877d2
Apply suggestions from code review
Turbo87 Feb 7, 2025
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
26 changes: 24 additions & 2 deletions src/openapi.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,36 @@ use utoipa::openapi::security::{ApiKey, ApiKeyValue, SecurityScheme};
use utoipa::{Modify, OpenApi};
use utoipa_axum::router::OpenApiRouter;

const DESCRIPTION: &str = r#"
__Experimental API documentation for the [crates.io](https://crates.io/)
package registry.__

This document describes the API used by the crates.io website, cargo
client, and other third-party tools to interact with the crates.io
registry.

__The API is under active development and may change at any time__,
though we will try to avoid breaking changes where possible.

Some parts of the API follow the "Registry Web API" spec documented
at <https://doc.rust-lang.org/cargo/reference/registry-web-api.html>
and can be considered stable.

Most parts of the API do not require authentication. The endpoints
that do require authentication are marked as such in the documentation,
with some requiring cookie authentication (usable only by the web UI)
and others requiring API token authentication (usable by cargo and
other clients).
"#;

#[derive(OpenApi)]
#[openapi(
info(
title = "crates.io",
description = "API documentation for the [crates.io](https://crates.io/) package registry",
description = DESCRIPTION,
terms_of_service = "https://crates.io/policies",
contact(name = "the crates.io team", email = "[email protected]"),
license(),
license(name = "MIT OR Apache-2.0", url = "https://github.com/rust-lang/crates.io/blob/main/README.md#%EF%B8%8F-license"),
version = "0.0.0",
),
modifiers(&SecurityAddon),
Expand Down
5 changes: 3 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 @@ -24,9 +24,10 @@ expression: response.json()
"email": "[email protected]",
"name": "the crates.io team"
},
"description": "API documentation for the [crates.io](https://crates.io/) package registry",
"description": "\n__Experimental API documentation for the [crates.io](https://crates.io/)\npackage registry.__\n\nThis document describes the API used by the crates.io website, cargo\nclient, and other third-party tools to interact with the crates.io\nregistry.\n\n__The API is under active development and may change at any time__,\nthough we will try to avoid breaking changes where possible.\n\nSome parts of the API follow the \"Registry Web API\" spec documented\nat <https://doc.rust-lang.org/cargo/reference/registry-web-api.html>\nand can be considered stable.\n\nMost parts of the API do not require authentication. The endpoints\nthat do require authentication are marked as such in the documentation,\nwith some requiring cookie authentication (usable only by the web UI)\nand others requiring API token authentication (usable by cargo and\nother clients).\n",
"license": {
"name": ""
"name": "MIT OR Apache-2.0",
"url": "https://github.com/rust-lang/crates.io/blob/main/README.md#%EF%B8%8F-license"
},
"termsOfService": "https://crates.io/policies",
"title": "crates.io",
Expand Down