Improve openapi documentation (#103)

v3xlabs · Apr 17, 2024 · 76c120b · 76c120b
1 parent fcf86f9
commit 76c120b
Show file tree

Hide file tree

Showing 15 changed files with 204 additions and 35 deletions.
diff --git a/server/Cargo.lock b/server/Cargo.lock
diff --git a/server/src/docs/html/favicon.png b/server/src/docs/html/favicon.png
diff --git a/server/src/docs/index.html → server/src/docs/html/index.html b/server/src/docs/index.html → server/src/docs/html/index.html
@@ -1,9 +1,11 @@
 <!DOCTYPE html>
 <html>
     <head>
-        <title>API Reference</title>
+        <title>enstate.rs - Lightweight ENS API</title>
         <meta charset="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <!-- favicon -->
+        <link rel="icon" href="/docs/favicon.png">
     </head>
     <body>
         <script

diff --git a/server/src/docs/mod.rs b/server/src/docs/mod.rs
@@ -1,20 +1,26 @@
 use crate::models::bulk::{BulkResponse, ListResponse};
 use crate::models::error::ErrorResponse;
 use crate::models::profile::ENSProfile;
-use utoipa::openapi::{ExternalDocs, License};
+use enstate_shared::meta::AppMeta;
+use enstate_shared::utils::vec;
+use utoipa::openapi::{ExternalDocs, License, Tag};
 use utoipa::OpenApi;
 
 #[derive(OpenApi)]
 #[openapi(
     info(
         title = "enstate.rs",
-        description = "A hosted ENS API allowing for easy access to ENS data.",
+        description = "A hosted ENS API allowing for easy access to ENS data.\n\nYou can checkout the source code, contribute, or host a version for yourself at [v3xlabs/enstate](https://github.com/v3xlabs/enstate).",
     ),
     paths(
         crate::routes::address::get, crate::routes::name::get, crate::routes::universal::get,
-        crate::routes::address::get_bulk, crate::routes::name::get_bulk, crate::routes::universal::get_bulk
+        crate::routes::address::get_bulk, crate::routes::name::get_bulk, crate::routes::universal::get_bulk,
+        crate::routes::address::get_bulk_sse, crate::routes::name::get_bulk_sse, crate::routes::universal::get_bulk_sse,
+        crate::routes::header::get,
+        crate::routes::image::get,
+        crate::routes::root::get,
     ),
-    components(schemas(ENSProfile, ListResponse<BulkResponse<ENSProfile>>, ErrorResponse))
+    components(schemas(ENSProfile, ListResponse<BulkResponse<ENSProfile>>, ErrorResponse, AppMeta))
 )]
 pub struct ApiDoc;
 
@@ -26,5 +32,22 @@ pub async fn openapi() -> String {
     doc.info.license = Some(license);
     doc.external_docs = Some(ExternalDocs::new("https://github.com/v3xlabs/enstate"));
 
+    let mut tag1 = Tag::default();
+    tag1.name = "Single Profile".to_string();
+    tag1.description = Some("If you want to resolve a single ENS Name / Profile you can do a single lookup in one of the following ways.".to_string());
+    let mut tag2 = Tag::default();
+    tag2.name = "Bulk Profiles".to_string();
+    tag2.description = Some("In some cases you might want to resolve a list of names or addresses. In this case you can use the bulk endpoints. This endpoint waits for all names to be resolved before returning a result.\n\nNote: You might prefer to use the [SSE Streaming Endpoints](#tag/stream-profiles) for a more responsive feel.".to_string());
+    let mut tag3 = Tag::default();
+    tag3.name = "Stream Profiles".to_string();
+    tag3.description = Some("In some cases you might want to resolve a list of names or addresses but have access to the results immediately. This endpoint returns its output via [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) as they are computed.\n\nNote: If you are looking for a simpler solution that return result aggregates checkout [Bulk Endpoints](#tag/bulk-profiles).".to_string());
+    let mut tag4 = Tag::default();
+    tag4.name = "Avatars & Banners".to_string();
+    tag4.description = Some("To save you the hassle of loading profiles, and extracting json fields, we have made a few endpoints that will make it easy for you to directly use image urls in your app.".to_string());
+    let mut tag5 = Tag::default();
+    tag5.name = "Deployment Information".to_string();
+
+    doc.tags = Some(vec![tag1, tag2, tag3, tag4, tag5]);
+
     doc.to_json().unwrap()
 }
diff --git a/server/src/http.rs b/server/src/http.rs
@@ -43,13 +43,17 @@ impl App {
 }
 
 pub fn setup(state: AppState) -> App {
+    let docs = Router::new()
+        .route("/openapi.json", get(crate::docs::openapi))
+        .route("/", get(scalar_handler))
+        .route("/favicon.png", get(scalar_favicon_handler));
+
     let router = Router::new()
         .route(
             "/",
             get(|| async { Redirect::temporary("/docs") }),
         )
-        .route("/docs", get(scalar_handler))
-        .route("/docs/openapi.json", get(crate::docs::openapi))
+        .nest("/docs", docs)
         .route("/this", get(routes::root::get))
         .route("/a/:address", get(routes::address::get))
         .route("/n/:name", get(routes::name::get))
@@ -72,6 +76,11 @@ pub fn setup(state: AppState) -> App {
 
 // Loads from docs/index.html with headers html
 async fn scalar_handler() -> Html<&'static str> {
-    let contents = include_str!("./docs/index.html");
+    let contents = include_str!("./docs/html/index.html");
     axum::response::Html(contents)
 }
+
+async fn scalar_favicon_handler() -> impl axum::response::IntoResponse {
+    let contents = include_bytes!("./docs/html/favicon.png");
+    contents
+}
diff --git a/server/src/routes/address.rs b/server/src/routes/address.rs
@@ -25,6 +25,7 @@ use crate::routes::{
 
 #[utoipa::path(
     get,
+    tag = "Single Profile",
     path = "/a/{address}",
     responses(
         (status = 200, description = "Successfully found address.", body = ENSProfile),
@@ -68,6 +69,7 @@ pub struct AddressGetBulkQuery {
 
 #[utoipa::path(
     get,
+    tag = "Bulk Profiles",
     path = "/bulk/a",
     responses(
         (status = 200, description = "Successfully found address.", body = BulkResponse<ENSProfile>),
@@ -106,6 +108,20 @@ pub async fn get_bulk(
     Ok(Json(joined))
 }
 
+#[utoipa::path(
+    get,
+    tag = "Stream Profiles",
+    path = "/sse/a",
+    responses(
+        (status = 200, description = "Successfully found address.", body = BulkResponse<ENSProfile>),
+        (status = BAD_REQUEST, description = "Invalid address.", body = ErrorResponse),
+        (status = NOT_FOUND, description = "No name was associated with this address.", body = ErrorResponse),
+        (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
+    ),
+    params(
+        ("addresses[]" = Vec<String>, Query, description = "Addresses to lookup name data for"),
+    )
+)]
 pub async fn get_bulk_sse(
     Qs(query): Qs<AddressGetBulkQuery>,
     State(state): State<Arc<crate::AppState>>,

diff --git a/server/src/routes/header.rs b/server/src/routes/header.rs
@@ -10,19 +10,30 @@ use enstate_shared::models::lookup::ENSLookup;
 
 use crate::routes::{FreshQuery, http_simple_status_error, profile_http_error_mapper, RouteError};
 
-// #[utoipa::path(
-//     get,
-//     path = "/h/{name_or_address}",
-//     responses(
-//         TODO: figure out body
-//         (status = 200, description = "Successfully found name or address.", body = ENSProfile),
-//         (status = NOT_FOUND, description = "No name or address could be found."),
-//         (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
-//     ),
-//     params(
-//         ("name_or_address" = String, Path, description = "Name or address to lookup the header for."),
-//     )
-// )]
+/// Banner Endpoint
+/// 
+/// This is the endpoint for getting an avatar image.
+/// It performs some pre-compute on the image to ensure it is `<img />` tag friendly.
+/// 
+/// To use in your app, you can use the following HTML:
+/// ```html
+/// <img src="https://enstate.rs/i/luc.eth" alt="luc.eth" />
+/// ```
+/// 
+/// Note: you should probably still have a fallback image in case the image is not found.
+#[utoipa::path(
+    head,
+    tag = "Avatars & Banners",
+    path = "/h/{name_or_address}",
+    responses(
+        (status = 303, description = "Redirects to the header image."),
+        (status = NOT_FOUND, description = "No name or address could be found."),
+        (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
+    ),
+    params(
+        ("name_or_address" = String, Path, description = "Name or address to lookup the header for."),
+    )
+)]
 pub async fn get(
     Path(name_or_address): Path<String>,
     Query(query): Query<FreshQuery>,

diff --git a/server/src/routes/image.rs b/server/src/routes/image.rs
@@ -10,19 +10,30 @@ use enstate_shared::models::lookup::ENSLookup;
 
 use crate::routes::{FreshQuery, http_simple_status_error, profile_http_error_mapper, RouteError};
 
-// #[utoipa::path(
-//     get,
-//     path = "/i/{name_or_address}",
-//     responses(
-//         TODO: figure out body
-//         (status = 200, description = "Successfully found name or address.", body = ENSProfile),
-//         (status = NOT_FOUND, description = "No name or address could be found."),
-//         (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
-//     ),
-//     params(
-//         ("name_or_address" = String, Path, description = "Name or address to lookup the image for."),
-//     )
-// )]
+/// Avatar Endpoint
+/// 
+/// This is the endpoint for getting an avatar image.
+/// It performs some pre-compute on the image to ensure it is `<img />` tag friendly.
+/// 
+/// To use in your app, you can use the following HTML:
+/// ```html
+/// <img src="https://enstate.rs/i/luc.eth" alt="luc.eth" />
+/// ```
+/// 
+/// Note: you should probably still have a fallback image in case the image is not found.
+#[utoipa::path(
+    head,
+    tag = "Avatars & Banners",
+    path = "/i/{name_or_address}",
+    responses(
+        (status = 303, description = "Redirects to the avatar image."),
+        (status = NOT_FOUND, description = "No name or address could be found."),
+        (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
+    ),
+    params(
+        ("name_or_address" = String, Path, description = "Name or address to lookup the image for."),
+    )
+)]
 pub async fn get(
     Path(name_or_address): Path<String>,
     Query(query): Query<FreshQuery>,

diff --git a/server/src/routes/name.rs b/server/src/routes/name.rs
@@ -20,6 +20,7 @@ use crate::routes::{profile_http_error_mapper, validate_bulk_input, FreshQuery,
 
 #[utoipa::path(
     get,
+    tag = "Single Profile",
     path = "/n/{name}",
     responses(
         (status = 200, description = "Successfully found name.", body = ENSProfile),
@@ -61,6 +62,7 @@ pub struct NameGetBulkQuery {
 
 #[utoipa::path(
     get,
+    tag = "Bulk Profiles",
     path = "/bulk/n",
     responses(
         (status = 200, description = "Successfully found name.", body = ListButWithLength<BulkResponse<Profile>>),
@@ -90,6 +92,18 @@ pub async fn get_bulk(
     Ok(Json(joined))
 }
 
+#[utoipa::path(
+    get,
+    tag = "Stream Profiles",
+    path = "/sse/n",
+    responses(
+        (status = 200, description = "Successfully found name.", body = ListButWithLength<BulkResponse<Profile>>),
+        (status = NOT_FOUND, description = "No name could be found.", body = ErrorResponse),
+    ),
+    params(
+        ("names[]" = Vec<String>, Query, description = "Names to lookup name data for"),
+    )
+)]
 pub async fn get_bulk_sse(
     Qs(query): Qs<NameGetBulkQuery>,
     State(state): State<Arc<crate::AppState>>,

diff --git a/server/src/routes/root.rs b/server/src/routes/root.rs
@@ -1,6 +1,17 @@
 use axum::Json;
 use enstate_shared::meta::{AppMeta, APP_META};
 
+/// Me Endpoint
+/// 
+/// This Endpoint returns the build information of the running process.
+#[utoipa::path(
+    get,
+    tag = "Deployment Information",
+    path = "/this",
+    responses(
+        (status = 200, description = "", body = AppMeta),
+    )
+)]
 #[allow(clippy::unused_async)]
 pub async fn get() -> Json<AppMeta> {
     Json(APP_META.clone())

diff --git a/server/src/routes/universal.rs b/server/src/routes/universal.rs
@@ -22,6 +22,7 @@ use crate::routes::{profile_http_error_mapper, validate_bulk_input, FreshQuery,
 
 #[utoipa::path(
     get,
+    tag = "Single Profile",
     path = "/u/{name_or_address}",
     responses(
         (status = 200, description = "Successfully found name or address.", body = ENSProfile),
@@ -64,6 +65,7 @@ pub struct UniversalGetBulkQuery {
 
 #[utoipa::path(
     get,
+    tag = "Bulk Profiles",
     path = "/bulk/u",
     responses(
         (status = 200, description = "Successfully found name or address.", body = BulkResponse<ENSProfile>),
@@ -92,6 +94,19 @@ pub async fn get_bulk(
     Ok(Json(joined))
 }
 
+#[utoipa::path(
+    get,
+    tag = "Stream Profiles",
+    path = "/sse/u",
+    responses(
+        (status = 200, description = "Successfully found name or address.", body = BulkResponse<ENSProfile>),
+        (status = NOT_FOUND, description = "No name or address could be found.", body = ErrorResponse),
+        (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
+    ),
+    params(
+        ("queries[]" = Vec<String>, Query, description = "Names to lookup name data for"),
+    )
+)]
 pub async fn get_bulk_sse(
     Qs(query): Qs<UniversalGetBulkQuery>,
     State(state): State<Arc<crate::AppState>>,

diff --git a/shared/Cargo.lock b/shared/Cargo.lock
diff --git a/shared/Cargo.toml b/shared/Cargo.toml
@@ -45,6 +45,7 @@ getrandom = { version = "0.2", features = ["js"] }
 wasm-bindgen-futures = "0.4.36"
 wasm-bindgen = { version = "0.2.86", features = ["serde-serialize"] }
 web-sys = { version = "0.3.63", features = ["console"] }
+utoipa = "4.2.0"
 
 [dev-dependencies]
 tokio = { version = "1", features = ["full"] }

diff --git a/shared/src/meta.rs b/shared/src/meta.rs
@@ -1,10 +1,15 @@
 use lazy_static::lazy_static;
+use utoipa::ToSchema;
 
-#[derive(Debug, Clone, serde::Serialize)]
+#[derive(Debug, Clone, serde::Serialize, ToSchema)]
 pub struct AppMeta {
+    #[schema(example = "fcf86f91")]
     pub rev: String,
+    #[schema(example = "enstate")]
     pub name: String,
+    #[schema(example = "git:fcf86f91")]
     pub version: String,
+    #[schema(example = "2024-04-17 16:27:49.963738487 UTC")]
     pub compile_time: String,
 }