Skip to content

Commit 8f8e0c2

Browse files
gzgz
committed
[docs] Fix excessive API description+links
Signed-off-by: Gerd Zellweger <mail@gerdzellweger.com>
1 parent c3675e6 commit 8f8e0c2

29 files changed

Lines changed: 575 additions & 430 deletions

File tree

‎crates/pipeline-manager/src/api/endpoints/api_key.rs‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,9 @@ pub(crate) struct NewApiKeyResponse {
4444
api_key: String,
4545
}
4646

47-
/// Retrieve the list of API keys.
47+
/// List API Keys
48+
///
49+
/// Retrieve a list of your API keys.
4850
#[utoipa::path(
4951
context_path = "/v0",
5052
security(("JSON web token (JWT) or API key" = [])),
@@ -54,7 +56,7 @@ pub(crate) struct NewApiKeyResponse {
5456
, body = [ApiKeyDescr]),
5557
(status = INTERNAL_SERVER_ERROR, body = ErrorResponse)
5658
),
57-
tag = "API keys"
59+
tag = "Platform"
5860
)]
5961
#[get("/api_keys")]
6062
pub(crate) async fn list_api_keys(
@@ -67,7 +69,9 @@ pub(crate) async fn list_api_keys(
6769
.json(&api_keys))
6870
}
6971

70-
/// Retrieve an API key.
72+
/// Get API Key
73+
///
74+
/// Retrieve the metadata of a specific API key by its name.
7175
#[utoipa::path(
7276
context_path = "/v0",
7377
security(("JSON web token (JWT) or API key" = [])),
@@ -83,7 +87,7 @@ pub(crate) async fn list_api_keys(
8387
, body = ErrorResponse
8488
, example = json!(examples::error_unknown_api_key()))
8589
),
86-
tag = "API keys"
90+
tag = "Platform"
8791
)]
8892
#[get("/api_keys/{api_key_name}")]
8993
pub(crate) async fn get_api_key(
@@ -98,7 +102,10 @@ pub(crate) async fn get_api_key(
98102
.json(&[api_key]))
99103
}
100104

101-
/// Create a new API key.
105+
/// Create API Key
106+
///
107+
/// Create a new API key with the specified name. The generated API key
108+
/// will be returned in the response and cannot be retrieved again later.
102109
#[utoipa::path(
103110
context_path = "/v0",
104111
security(("JSON web token (JWT) or API key" = [])),
@@ -111,7 +118,7 @@ pub(crate) async fn get_api_key(
111118
, body = ErrorResponse
112119
, example = json!(examples::error_duplicate_name())),
113120
),
114-
tag = "API keys"
121+
tag = "Platform"
115122
)]
116123
#[post("/api_keys")]
117124
pub(crate) async fn post_api_key(
@@ -146,7 +153,9 @@ pub(crate) async fn post_api_key(
146153
Ok(res)
147154
}
148155

149-
/// Delete an API key.
156+
/// Delete API Key
157+
///
158+
/// Remove an API key by its name.
150159
#[utoipa::path(
151160
context_path = "/v0",
152161
security(("JSON web token (JWT) or API key" = [])),
@@ -160,7 +169,7 @@ pub(crate) async fn post_api_key(
160169
, body = ErrorResponse
161170
, example = json!(examples::error_unknown_api_key()))
162171
),
163-
tag = "API keys"
172+
tag = "Platform"
164173
)]
165174
#[delete("/api_keys/{api_key_name}")]
166175
pub(crate) async fn delete_api_key(

‎crates/pipeline-manager/src/api/endpoints/cluster_healthz.rs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,17 @@ use crate::{
77
error::ManagerError,
88
};
99

10+
/// Check Cluster Health
11+
///
12+
/// Retrieve the health status of the Feldera control-plane.
1013
#[utoipa::path(
1114
context_path = "/v0",
1215
security(("JSON web token (JWT) or API key" = [])),
1316
responses(
1417
(status = 200, description = "All services healthy", body = HealthStatus),
1518
(status = 503, description = "One or more services unhealthy", body = HealthStatus)
16-
)
19+
),
20+
tag = "Platform"
1721
)]
1822
#[get("/cluster_healthz")]
1923
pub(crate) async fn get_health(state: WebData<ServerState>) -> Result<HttpResponse, ManagerError> {

‎crates/pipeline-manager/src/api/endpoints/config.rs‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,9 @@ impl Configuration {
128128
}
129129
}
130130

131-
/// Retrieve general configuration.
131+
/// Get Platform Config
132+
///
133+
/// Retrieve configuration of the Feldera Platform.
132134
#[utoipa::path(
133135
context_path = "/v0",
134136
security(("JSON web token (JWT) or API key" = [])),
@@ -141,7 +143,7 @@ impl Configuration {
141143
, description = "Request failed."
142144
, body = ErrorResponse),
143145
),
144-
tag = "Configuration"
146+
tag = "Platform"
145147
)]
146148
#[get("/config")]
147149
pub(crate) async fn get_config(
@@ -153,7 +155,9 @@ pub(crate) async fn get_config(
153155
Ok(HttpResponse::Ok().json(config))
154156
}
155157

156-
/// Retrieve authentication provider configuration.
158+
/// Get Auth Config
159+
///
160+
/// Retrieve the authentication provider configuration.
157161
#[utoipa::path(
158162
path="/config/authentication",
159163
responses(
@@ -166,7 +170,7 @@ pub(crate) async fn get_config(
166170
, description = "Request failed."
167171
, body = ErrorResponse),
168172
),
169-
tag = "Configuration"
173+
tag = "Platform"
170174
)]
171175
#[get("/config/authentication")]
172176
pub(crate) async fn get_config_authentication(
@@ -180,7 +184,9 @@ pub(crate) async fn get_config_authentication(
180184
Ok(HttpResponse::Ok().json(&auth_config.provider))
181185
}
182186

183-
/// Retrieve the list of demos.
187+
/// List Demos
188+
///
189+
/// Retrieve the list of demos available in the WebConsole.
184190
#[utoipa::path(
185191
context_path = "/v0",
186192
security(("JSON web token (JWT) or API key" = [])),
@@ -193,7 +199,7 @@ pub(crate) async fn get_config_authentication(
193199
, description = "Failed to read demos from the demos directories"
194200
, body = ErrorResponse),
195201
),
196-
tag = "Configuration",
202+
tag = "Platform",
197203
)]
198204
#[get("/config/demos")]
199205
pub(crate) async fn get_config_demos(
@@ -225,7 +231,9 @@ impl SessionInfo {
225231
}
226232
}
227233

228-
/// Retrieve current session information.
234+
/// Get Session
235+
///
236+
/// Retrieve login session information for your current user session.
229237
#[utoipa::path(
230238
context_path = "/v0",
231239
security(("JSON web token (JWT) or API key" = [])),
@@ -238,7 +246,7 @@ impl SessionInfo {
238246
, description = "Request failed."
239247
, body = ErrorResponse),
240248
),
241-
tag = "Configuration"
249+
tag = "Platform"
242250
)]
243251
#[get("/config/session")]
244252
pub(crate) async fn get_config_session(

‎crates/pipeline-manager/src/api/endpoints/metrics.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ use actix_web::{
1010
use awc::body::MessageBody as _;
1111
use feldera_types::runtime_status::RuntimeStatus;
1212

13+
/// List All Metrics
14+
///
1315
/// Retrieve the metrics of all running pipelines belonging to this tenant.
1416
///
1517
/// The metrics are collected by making individual HTTP requests to `/metrics`
@@ -24,7 +26,7 @@ use feldera_types::runtime_status::RuntimeStatus;
2426
, content_type = "text/plain"
2527
, body = Vec<u8>),
2628
),
27-
tag = "Metrics"
29+
tag = "Metrics & Debugging"
2830
)]
2931
#[get("/metrics")]
3032
pub(crate) async fn get_metrics(

0 commit comments

Comments
 (0)