Skip to content

Commit

Permalink
Tweak a few API endpoint summaries and descriptions (#4999)
Browse files Browse the repository at this point in the history 
This PR only changes descriptive text in the OpenAPI definition, so it
doesn't really have to go into the RC, but it is also low risk to pull
in.

---

Saw these on the [integration branch
docs](https://docs-git-integration-oxidecomputer.vercel.app/api/ip_pool_silo_update)
and felt they could use some work.

![Screenshot 2024-02-06 at 10 06
38 AM](https://github.com/oxidecomputer/omicron/assets/3612203/c2dbdf3d-da69-43f6-9568-85476af2d48e)

Also got rid of a few stray periods:

![Screenshot 2024-02-06 at 10 06
50 AM](https://github.com/oxidecomputer/omicron/assets/3612203/42a70202-5cb2-49b2-9da5-5a57b49a7b99)
  • Loading branch information
@david-crespo
david-crespo authored Feb 6, 2024
1 parent 9576766 commit 7e0ce99
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 28 deletions.
39 changes: 24 additions & 15 deletions nexus/src/external_api/http_entrypoints.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -759,7 +759,11 @@ async fn silo_view(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// List IP pools available within silo
/// List IP pools linked to silo
///
/// Linked IP pools are available to users in the specified silo. A silo can
/// have at most one default pool. IPs are allocated from the default pool when
/// users ask for one without specifying a pool.
#[endpoint {
method = GET,
path = "/v1/system/silos/{silo}/ip-pools",
Expand Down Expand Up @@ -803,7 +807,7 @@ async fn silo_ip_pool_list(

/// Delete a silo
///
/// Delete a silo by name.
/// Delete a silo by name or ID.
#[endpoint {
method = DELETE,
path = "/v1/system/silos/{silo}",
Expand Down Expand Up @@ -1569,7 +1573,11 @@ async fn ip_pool_silo_list(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Make an IP pool available within a silo
/// Link an IP pool to a silo
///
/// Users in linked silos can allocate external IPs from this pool for their
/// instances. A silo can have at most one default pool. IPs are allocated from
/// the default pool when users ask for one without specifying a pool.
#[endpoint {
method = POST,
path = "/v1/system/ip-pools/{pool}/silos",
Expand Down Expand Up @@ -1620,10 +1628,12 @@ async fn ip_pool_silo_unlink(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Make an IP pool default or not-default for a silo
/// Make IP pool default for silo
///
/// When a pool is made default for a silo, any existing default will remain
/// linked to the silo, but will no longer be the default.
/// When a user asks for an IP (e.g., at instance create time) without
/// specifying a pool, the IP comes from the default pool if a default is
/// configured. When a pool is made the default for a silo, any existing default
/// will remain linked to the silo, but will no longer be the default.
#[endpoint {
method = PUT,
path = "/v1/system/ip-pools/{pool}/silos/{silo}",
Expand All @@ -1650,7 +1660,7 @@ async fn ip_pool_silo_update(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Fetch the IP pool used for Oxide services
/// Fetch the Oxide service IP pool
#[endpoint {
method = GET,
path = "/v1/system/ip-pools-service",
Expand Down Expand Up @@ -1765,10 +1775,9 @@ async fn ip_pool_range_remove(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// List ranges for the IP pool used for Oxide services
/// List IP ranges for the Oxide service pool
///
/// List ranges for the IP pool used for Oxide services. Ranges are ordered by
/// their first address.
/// Ranges are ordered by their first address.
#[endpoint {
method = GET,
path = "/v1/system/ip-pools-service/ranges",
Expand Down Expand Up @@ -1809,7 +1818,7 @@ async fn ip_pool_service_range_list(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Add a range to an IP pool used for Oxide services
/// Add IP range to Oxide service pool
#[endpoint {
method = POST,
path = "/v1/system/ip-pools-service/ranges/add",
Expand All @@ -1830,7 +1839,7 @@ async fn ip_pool_service_range_add(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Remove a range from an IP pool used for Oxide services
/// Remove IP range from Oxide service pool
#[endpoint {
method = POST,
path = "/v1/system/ip-pools-service/ranges/remove",
Expand Down Expand Up @@ -3539,7 +3548,7 @@ async fn networking_bgp_announce_set_delete(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Enable a BFD session.
/// Enable a BFD session
#[endpoint {
method = POST,
path = "/v1/system/networking/bfd-enable",
Expand All @@ -3560,7 +3569,7 @@ async fn networking_bfd_enable(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Disable a BFD session.
/// Disable a BFD session
#[endpoint {
method = POST,
path = "/v1/system/networking/bfd-disable",
Expand All @@ -3581,7 +3590,7 @@ async fn networking_bfd_disable(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Get BFD status.
/// Get BFD status
#[endpoint {
method = GET,
path = "/v1/system/networking/bfd-status",
Expand Down
28 changes: 15 additions & 13 deletions openapi/nexus.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5331,7 +5331,8 @@
"tags": [
"system/networking"
],
"summary": "Make an IP pool available within a silo",
"summary": "Link an IP pool to a silo",
"description": "Users in linked silos can allocate external IPs from this pool for their instances. A silo can have at most one default pool. IPs are allocated from the default pool when users ask for one without specifying a pool.",
"operationId": "ip_pool_silo_link",
"parameters": [
{
Expand Down Expand Up @@ -5379,8 +5380,8 @@
"tags": [
"system/networking"
],
"summary": "Make an IP pool default or not-default for a silo",
"description": "When a pool is made default for a silo, any existing default will remain linked to the silo, but will no longer be the default.",
"summary": "Make IP pool default for silo",
"description": "When a user asks for an IP (e.g., at instance create time) without specifying a pool, the IP comes from the default pool if a default is configured. When a pool is made the default for a silo, any existing default will remain linked to the silo, but will no longer be the default.",
"operationId": "ip_pool_silo_update",
"parameters": [
{
Expand Down Expand Up @@ -5472,7 +5473,7 @@
"tags": [
"system/networking"
],
"summary": "Fetch the IP pool used for Oxide services",
"summary": "Fetch the Oxide service IP pool",
"operationId": "ip_pool_service_view",
"responses": {
"200": {
Expand All @@ -5499,8 +5500,8 @@
"tags": [
"system/networking"
],
"summary": "List ranges for the IP pool used for Oxide services",
"description": "List ranges for the IP pool used for Oxide services. Ranges are ordered by their first address.",
"summary": "List IP ranges for the Oxide service pool",
"description": "Ranges are ordered by their first address.",
"operationId": "ip_pool_service_range_list",
"parameters": [
{
Expand Down Expand Up @@ -5552,7 +5553,7 @@
"tags": [
"system/networking"
],
"summary": "Add a range to an IP pool used for Oxide services",
"summary": "Add IP range to Oxide service pool",
"operationId": "ip_pool_service_range_add",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5589,7 +5590,7 @@
"tags": [
"system/networking"
],
"summary": "Remove a range from an IP pool used for Oxide services",
"summary": "Remove IP range from Oxide service pool",
"operationId": "ip_pool_service_range_remove",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5909,7 +5910,7 @@
"tags": [
"system/networking"
],
"summary": "Disable a BFD session.",
"summary": "Disable a BFD session",
"operationId": "networking_bfd_disable",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5939,7 +5940,7 @@
"tags": [
"system/networking"
],
"summary": "Enable a BFD session.",
"summary": "Enable a BFD session",
"operationId": "networking_bfd_enable",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5969,7 +5970,7 @@
"tags": [
"system/networking"
],
"summary": "Get BFD status.",
"summary": "Get BFD status",
"operationId": "networking_bfd_status",
"responses": {
"200": {
Expand Down Expand Up @@ -6980,7 +6981,7 @@
"system/silos"
],
"summary": "Delete a silo",
"description": "Delete a silo by name.",
"description": "Delete a silo by name or ID.",
"operationId": "silo_delete",
"parameters": [
{
Expand Down Expand Up @@ -7011,7 +7012,8 @@
"tags": [
"system/silos"
],
"summary": "List IP pools available within silo",
"summary": "List IP pools linked to silo",
"description": "Linked IP pools are available to users in the specified silo. A silo can have at most one default pool. IPs are allocated from the default pool when users ask for one without specifying a pool.",
"operationId": "silo_ip_pool_list",
"parameters": [
{
Expand Down

0 comments on commit 7e0ce99

Please sign in to comment.