From eb389a394943d77a48adbac1e8b6be1be2b56bc6 Mon Sep 17 00:00:00 2001 From: "Luis Gustavo S. Barreto" Date: Sat, 30 May 2026 01:29:16 -0300 Subject: [PATCH] feat(openapi): add customer-facing API documentation build The published OpenAPI was a single spec exposing every route (admin, internal, billing, auth) to customers. Split it into two builds from one source: the full spec stays the internal source of truth for client generation and response validation, and a new filtered build is the customer-facing documentation. A drop-non-customer Redocly decorator keeps only the namespace-scoped, api-key usable surface: it drops /admin and /internal, operations that do not accept an api-key, and x-internal overrides, and strips the jwt scheme so the docs show api-key only. Other changes needed to make that build correct: - upgrade @redocly/cli to 2.31.5 (the pinned beta lacked decorators) and fix the schema errors the newer linter caught - fix edition composition: cloud and enterprise are siblings over a shared base, not a linear chain; enterprise no longer inherits cloud-only routes and cloud now carries the admin surface - align spec security with the Go routes (drop api-key where the handler blocks it or requires an owner-only permission) - relocate the internal session update to /internal, and tidy operation copy, tags, and the home pages --- .github/workflows/openapi-cd.yml | 10 +- .github/workflows/openapi-ci.yml | 12 +- .github/workflows/validate-ui-react.yml | 2 +- openapi/.gitignore | 1 + openapi/Dockerfile | 2 +- openapi/README.md | 20 +- openapi/main.go | 10 + openapi/plugins/customer-filter.js | 211 ++++++++++++++++++ openapi/redocly.yaml | 40 ++-- openapi/spec/cloud-openapi.yaml | 109 +++++++-- openapi/spec/community-openapi.yaml | 59 +++-- .../spec/components/schemas/namespace.yaml | 2 + openapi/spec/components/schemas/security.yaml | 5 +- openapi/spec/components/schemas/session.yaml | 1 + .../spec/components/schemas/webendpoint.yaml | 1 + openapi/spec/enterprise-openapi.yaml | 99 ++++++-- openapi/spec/openapi.yaml | 23 +- .../spec/paths/admin@api@firewall@rules.yaml | 4 +- .../paths/admin@api@firewall@rules@{id}.yaml | 6 +- .../paths/admin@api@sshkeys@public-keys.yaml | 4 +- openapi/spec/paths/api@auth@ssh.yaml | 1 - .../spec/paths/api@auth@token@{tenant}.yaml | 1 - openapi/spec/paths/api@auth@user.yaml | 1 - openapi/spec/paths/api@billing@customer.yaml | 2 - .../spec/paths/api@billing@device-choice.yaml | 1 - .../paths/api@billing@devices-most-used.yaml | 1 - openapi/spec/paths/api@billing@evaluate.yaml | 1 - .../api@billing@paymentmethod@attach.yaml | 1 - .../api@billing@paymentmethod@default.yaml | 1 - .../api@billing@paymentmethod@detach.yaml | 1 - openapi/spec/paths/api@billing@report.yaml | 1 - .../spec/paths/api@billing@subscription.yaml | 2 - .../api@billing@{id}@payment-method.yaml | 3 - openapi/spec/paths/api@containers.yaml | 4 +- openapi/spec/paths/api@containers@{uid}.yaml | 8 +- .../api@containers@{uid}@tags@{name}.yaml | 6 +- .../paths/api@containers@{uid}@{status}.yaml | 4 +- openapi/spec/paths/api@devices.yaml | 4 +- openapi/spec/paths/api@devices@resolve.yaml | 10 +- openapi/spec/paths/api@devices@{uid}.yaml | 8 +- .../spec/paths/api@devices@{uid}@accept.yaml | 4 +- .../spec/paths/api@devices@{uid}@offline.yaml | 1 - .../paths/api@devices@{uid}@tags@{name}.yaml | 6 +- .../spec/paths/api@devices@{uid}@tunnels.yaml | 8 +- .../api@devices@{uid}@tunnels@{address}.yaml | 2 +- .../paths/api@devices@{uid}@{status}.yaml | 4 +- openapi/spec/paths/api@firewall@rules.yaml | 10 +- .../spec/paths/api@firewall@rules@{id}.yaml | 12 +- openapi/spec/paths/api@healthcheck.yaml | 1 + openapi/spec/paths/api@namespaces.yaml | 2 + .../spec/paths/api@namespaces@api-key.yaml | 2 +- .../spec/paths/api@namespaces@{tenant}.yaml | 13 +- ...{tenant}@containers@{uid}@tags@{name}.yaml | 2 +- ...es@{tenant}@devices@{uid}@tags@{name}.yaml | 2 +- .../api@namespaces@{tenant}@members.yaml | 1 + ...s@{tenant}@members@{id}@accept-invite.yaml | 1 + .../paths/api@namespaces@{tenant}@tags.yaml | 6 +- openapi/spec/paths/api@sessions.yaml | 4 +- openapi/spec/paths/api@sessions@{uid}.yaml | 28 +-- .../spec/paths/api@sshkeys@public-keys.yaml | 13 +- ...api@sshkeys@public-keys@{fingerprint}.yaml | 14 +- openapi/spec/paths/api@stats.yaml | 6 +- openapi/spec/paths/api@tags.yaml | 8 +- openapi/spec/paths/api@tags@{name}.yaml | 4 +- openapi/spec/paths/api@user@mfa@auth.yaml | 1 + openapi/spec/paths/api@user@mfa@recovery.yaml | 1 + openapi/spec/paths/api@user@mfa@reset.yaml | 1 + .../paths/api@user@mfa@reset@{user-id}.yaml | 1 + openapi/spec/paths/api@users@security.yaml | 25 --- openapi/spec/paths/api@web-endpoints.yaml | 8 +- .../paths/api@web-endpoints@{address}.yaml | 4 +- .../spec/paths/internal@sessions@{uid}.yaml | 30 +++ openapi/static/customer.html | 27 +++ ui-react/Dockerfile | 3 +- ui-react/scripts/generate-client.sh | 2 +- 75 files changed, 666 insertions(+), 273 deletions(-) create mode 100644 openapi/plugins/customer-filter.js delete mode 100644 openapi/spec/paths/api@users@security.yaml create mode 100644 openapi/spec/paths/internal@sessions@{uid}.yaml create mode 100644 openapi/static/customer.html diff --git a/.github/workflows/openapi-cd.yml b/.github/workflows/openapi-cd.yml index 149ac9f1653..94bf9468756 100644 --- a/.github/workflows/openapi-cd.yml +++ b/.github/workflows/openapi-cd.yml @@ -21,11 +21,15 @@ jobs: - name: Setup bundler run: | - npm install -g @redocly/cli@1.0.0-beta.100 + npm install -g @redocly/cli@2.31.5 mkdir bundled/ - - name: Bundle - run: redocly bundle openapi/spec/openapi.yaml -o bundled/openapi.yaml + - name: Bundle customer documentation + working-directory: openapi + run: | + redocly bundle community-customer@v1 -o ../bundled/community-openapi.yaml + redocly bundle cloud-customer@v1 -o ../bundled/cloud-openapi.yaml + redocly bundle enterprise-customer@v1 -o ../bundled/enterprise-openapi.yaml - name: Upload artifacts uses: actions/upload-artifact@v7 diff --git a/.github/workflows/openapi-ci.yml b/.github/workflows/openapi-ci.yml index da14170bb41..dbd48aeaa22 100644 --- a/.github/workflows/openapi-ci.yml +++ b/.github/workflows/openapi-ci.yml @@ -31,7 +31,15 @@ jobs: run: prettier -c openapi/spec/**/*.yaml - name: Setup Redocly - run: npm install -g @redocly/cli@1.0.0-beta.100 + run: npm install -g @redocly/cli@2.31.5 - name: Run Redocly lint - run: redocly lint openapi/spec/openapi.yaml + working-directory: openapi + run: redocly lint spec/openapi.yaml spec/community-openapi.yaml spec/cloud-openapi.yaml spec/enterprise-openapi.yaml + + - name: Bundle customer specs (exercise the customer-filter plugin) + working-directory: openapi + run: | + for edition in community cloud enterprise; do + redocly bundle "${edition}-customer@v1" -o "/tmp/${edition}-customer.json" + done diff --git a/.github/workflows/validate-ui-react.yml b/.github/workflows/validate-ui-react.yml index cc2ad003ad1..270e79752f9 100644 --- a/.github/workflows/validate-ui-react.yml +++ b/.github/workflows/validate-ui-react.yml @@ -60,7 +60,7 @@ jobs: if: steps.filter.outputs[matrix.app] == 'true' working-directory: ui-react run: | - npx @redocly/cli@1.0.0-beta.100 bundle ../openapi/spec/openapi.yaml -o /tmp/openapi.json --force + npx @redocly/cli@2.31.5 bundle ../openapi/spec/openapi.yaml -o /tmp/openapi.json --force OPENAPI_SPEC_PATH=/tmp/openapi.json npm run generate -w ${{ matrix.workspace }} - name: Unit test [${{ matrix.app }}] diff --git a/openapi/.gitignore b/openapi/.gitignore index 2309f5e9e8f..b67d7aca0db 100644 --- a/openapi/.gitignore +++ b/openapi/.gitignore @@ -4,3 +4,4 @@ bundled/ .env openapi.json +customer.json diff --git a/openapi/Dockerfile b/openapi/Dockerfile index 71c91836b07..a71f4c03c31 100644 --- a/openapi/Dockerfile +++ b/openapi/Dockerfile @@ -7,7 +7,7 @@ RUN apk add --no-cache openssl nodejs npm openjdk11-jre git RUN npm install -g @openapitools/openapi-generator-cli -RUN npm install -g @redocly/cli@1.0.0-beta.100 +RUN npm install -g @redocly/cli@2.31.5 RUN npm install -g @stoplight/prism-cli@4.6.1 diff --git a/openapi/README.md b/openapi/README.md index c993774e7bb..a02a59682b3 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -22,7 +22,25 @@ OpenAPI](http://localhost/openapi/) in any OpenAPI file after a page reload. Its usage is simple too, you just need `up` the `shellhub-io/shellhub` containers in development mode and access the URL. -- Access the URL [http://localhost/openapi/preview](http://localhost/openapi) to check the preview. +- Access the URL [http://localhost/openapi/](http://localhost/openapi/) to check the preview. + +### Full spec vs customer docs + +There are two builds of every edition spec, from the same source: + +- **Full spec** — the internal source of truth, documenting every route (public, + internal, and admin). It backs the frontend client generation and the + dev-mode response validator. This is what the preview above serves. +- **Customer docs** — the published, customer-facing documentation. A + `drop-non-customer` decorator (`plugins/customer-filter.js`) keeps only the + namespace-scoped, API-key usable surface: it drops `/admin` and `/internal` + routes, operations that do not accept an API key, and anything flagged + `x-internal: true`; it also strips the `jwt` scheme so the docs show api-key + only. These are the `*-customer` API entries in `redocly.yaml`, published on + release by `openapi-cd.yml`. + +Preview the customer docs locally at +[http://localhost/openapi/customer.html](http://localhost/openapi/customer.html). ### Lint diff --git a/openapi/main.go b/openapi/main.go index d8424cd0be6..ac89b9b4ea6 100644 --- a/openapi/main.go +++ b/openapi/main.go @@ -35,6 +35,16 @@ func main() { log.Fatalf("error: failed to bundle the openapi spec: %v", err) } + // Also bundle the customer-facing (filtered) spec so it can be previewed at + // /openapi/customer.html. This applies the drop-non-customer decorator, + // leaving only the namespace-scoped, api-key usable surface. A failure here + // must not stop the server: the full spec above is what the frontend codegen + // and the response validator depend on. + customerAPI := edition + "-customer@v1" + if err := exec.Command("redocly", "bundle", customerAPI, "-o", "static/customer.json").Run(); err != nil { //nolint:gosec + log.Printf("warning: failed to bundle the customer OpenAPI preview (%s): %v", customerAPI, err) + } + mux := http.NewServeMux() // NOTE: Gateway proxy to serve the OpenAPI spec and the Redoc UI. directly on the /openapi path. diff --git a/openapi/plugins/customer-filter.js b/openapi/plugins/customer-filter.js new file mode 100644 index 00000000000..c5edc580d80 --- /dev/null +++ b/openapi/plugins/customer-filter.js @@ -0,0 +1,211 @@ +// Redocly decorator that keeps only the customer-facing surface of the API. +// +// An operation is kept when it is usable by a customer integration, which means +// all of: +// 1. its path is not under /admin or /internal (those surfaces are never +// customer facing), and +// 2. it accepts the `api-key` security scheme (api-key auth is namespace +// related and not tied to a user), and +// 3. it is not explicitly flagged with `x-internal: true`. +// +// Everything else (admin, internal, login/auth, account, billing, MFA, user and +// the few api-key accepting but account level routes) is dropped. Path items +// left without any operation are removed too. +// +// Operations are removed at the operation level, because deleting a whole path +// item from its parent does not stick for paths composed through a +// `paths: $ref` import (cloud and enterprise specs). Empty path items are then +// pruned in the Root visitor, which runs on the fully assembled document. +// +// The `x-internal` flag is an explicit override for operations that accept an +// api-key but are still not part of the customer integration surface (for +// example create/list namespace, leave namespace, list api keys, member +// invitations). + +// Home page (info.description) for the customer docs. The full spec keeps its +// own internal-facing description; this one is injected only into the filtered +// build. +const CUSTOMER_DESCRIPTION = `Programmatic access to your namespace: devices, sessions, SSH public keys, +tags, firewall rules, and more. + +## Base URL + +Endpoints are served under \`/api\` on your ShellHub server. On ShellHub Cloud +the base URL is \`https://cloud.shellhub.io/api\`. + +## Authentication + +Send your API key in the \`X-API-KEY\` header: + +\`\`\` +curl https://cloud.shellhub.io/api/devices -H "X-API-KEY: " +\`\`\` + +An API key belongs to a single namespace and is not tied to a user. Create one +in the console under **Namespace → API Keys**. Every endpoint operates within +the key's namespace, so the namespace scope is implicit throughout this +reference. + +## Pagination + +List endpoints accept \`page\` and \`per_page\` query parameters and return the +total item count in the \`X-Total-Count\` response header. + +## Errors + +Errors use standard HTTP status codes. \`401\` means the API key is missing or +invalid; \`403\` means the key's role does not allow the operation.`; + +const HTTP_METHODS = [ + 'get', + 'put', + 'post', + 'delete', + 'options', + 'head', + 'patch', + 'trace', +]; + +const INTERNAL_PREFIXES = ['/admin', '/internal']; + +// Edition and audience markers used as tags across the specs. They are not +// resources, so they are stripped from the customer docs to leave a clean +// resource-based grouping (devices, sessions, rules, ...). +const NON_RESOURCE_TAGS = new Set([ + 'community', + 'cloud', + 'enterprise', + 'internal', + 'external', +]); + +function operationAcceptsApiKey(operation) { + const security = operation.security; + + return ( + Array.isArray(security) && + security.some( + (requirement) => + requirement && + Object.prototype.hasOwnProperty.call(requirement, 'api-key'), + ) + ); +} + +function isCustomerOperation(operation) { + return operation['x-internal'] !== true && operationAcceptsApiKey(operation); +} + +function hasAnyOperation(pathItem) { + return HTTP_METHODS.some((method) => pathItem[method] !== undefined); +} + +function DropNonCustomer() { + return { + PathItem: { + enter(pathItem, ctx) { + const path = ctx.key; + const isInternalPath = + typeof path === 'string' && + INTERNAL_PREFIXES.some((prefix) => path.startsWith(prefix)); + + for (const method of HTTP_METHODS) { + const operation = pathItem[method]; + + if (operation === undefined) { + continue; + } + + if (isInternalPath || !isCustomerOperation(operation)) { + delete pathItem[method]; + + continue; + } + + // Kept operation: clean it up for the customer docs. + if (Array.isArray(operation.tags)) { + operation.tags = operation.tags.filter( + (tag) => !NON_RESOURCE_TAGS.has(tag), + ); + } + + // The customer docs are api-key only, so drop the jwt alternative + // from the security requirements (it stays in the full spec). + if (Array.isArray(operation.security)) { + operation.security = operation.security.filter( + (requirement) => + requirement && + Object.prototype.hasOwnProperty.call(requirement, 'api-key'), + ); + } + } + }, + }, + Root: { + leave(root) { + if (!root.paths) { + return; + } + + for (const path of Object.keys(root.paths)) { + if (!hasAnyOperation(root.paths[path])) { + delete root.paths[path]; + } + } + + // Drop root tags that no surviving operation references, so the + // rendered docs do not show empty tag groups. + if (Array.isArray(root.tags)) { + const usedTags = new Set(); + + for (const pathItem of Object.values(root.paths)) { + for (const method of HTTP_METHODS) { + const operation = pathItem[method]; + + if (operation && Array.isArray(operation.tags)) { + operation.tags.forEach((tag) => usedTags.add(tag)); + } + } + } + + const seenTags = new Set(); + root.tags = root.tags.filter((tag) => { + if (!usedTags.has(tag.name) || seenTags.has(tag.name)) { + return false; + } + + seenTags.add(tag.name); + + return true; + }); + } + + // The customer docs authenticate only with api-key, so drop the jwt + // security scheme. The full spec keeps it. + if (root.components && root.components.securitySchemes) { + delete root.components.securitySchemes.jwt; + } + + // Replace the home page with the customer-facing description. The full + // spec keeps its internal-facing one. + if (root.info) { + root.info.description = CUSTOMER_DESCRIPTION; + } + }, + }, + }; +} + +function customerFilterPlugin() { + return { + id: 'customer-filter', + decorators: { + oas3: { + 'drop-non-customer': DropNonCustomer, + }, + }, + }; +} + +module.exports = customerFilterPlugin; diff --git a/openapi/redocly.yaml b/openapi/redocly.yaml index 7c4c6664ee2..2fa370e498d 100644 --- a/openapi/redocly.yaml +++ b/openapi/redocly.yaml @@ -1,13 +1,5 @@ -# This is the Redocly configuration file, and it is used by Redocly CLI and other Redocly apps to control their behavior -# — from the strictness of the lint command, to how Redocly renders your docs. -# -# - Workflows uses it in the API registry to manage your APIs and control advanced features like region and link resolution. -# - Workflows and on-premise tools use it to apply your features and theme when building API docs. -# - Redocly's VS Code extension uses it for linting criteria, to apply custom settings for live documentation previews, -# and to identify the path API definition root files. -# -# https://redocly.com/docs/cli/configuration/ -organization: shellhub +# Redocly configuration. Controls linting and how the OpenAPI specs are bundled +# and rendered. https://redocly.com/docs/cli/configuration/ # This extends the recommended configuration values. # https://redocly.com/docs/cli/rules/#recommended-config @@ -17,7 +9,12 @@ extends: rules: no-ambiguous-paths: off +plugins: + - ./plugins/customer-filter.js + apis: + # Full specs: the internal source of truth, consumed by the frontend codegen + # and the dev-mode response validator. No filtering applied. community@v1: root: ./spec/community-openapi.yaml cloud@v1: @@ -25,9 +22,20 @@ apis: enterprise@v1: root: ./spec/enterprise-openapi.yaml -features.openapi: - schemaExpansionLevel: 2 - generateCodeSamples: - languages: - - lang: curl - - lang: Go + # Customer specs: the published documentation. The drop-non-customer decorator + # keeps only the namespace-scoped, api-key usable surface. + community-customer@v1: + root: ./spec/community-openapi.yaml + decorators: + customer-filter/drop-non-customer: on + remove-unused-components: on + cloud-customer@v1: + root: ./spec/cloud-openapi.yaml + decorators: + customer-filter/drop-non-customer: on + remove-unused-components: on + enterprise-customer@v1: + root: ./spec/enterprise-openapi.yaml + decorators: + customer-filter/drop-non-customer: on + remove-unused-components: on diff --git a/openapi/spec/cloud-openapi.yaml b/openapi/spec/cloud-openapi.yaml index 5b6457aaecb..8f977405c40 100644 --- a/openapi/spec/cloud-openapi.yaml +++ b/openapi/spec/cloud-openapi.yaml @@ -2,13 +2,14 @@ openapi: 3.0.3 info: title: ShellHub Cloud OpenAPI description: | - > NOTICE: THE API IS NOT STABLE YET; ERROR AND INCONSISTENCIES MAY OCCUR. - - ShellHub Cloud OpenAPI specification. - - It documents all routes provided by ShellHub Cloud. + Full reference for the ShellHub Cloud API, covering public, internal, and + service-to-service routes. This is the internal source of truth used for + client generation and response validation; the customer-facing documentation + is a filtered build that exposes only the namespace-scoped, API-key usable + surface. contact: - email: contato@ossystems.com.br + name: ShellHub + email: contact@shellhub.io license: name: Apache License 2.0 url: https://github.com/shellhub-io/shellhub/blob/master/LICENSE.md @@ -20,14 +21,41 @@ components: securitySchemes: $ref: ./components/schemas/security.yaml tags: - - name: cloud - description: Routes provided by ShellHub Cloud API. + - name: devices + x-displayName: Devices + description: List, inspect, accept, reject, rename, and delete devices, and manage their custom fields. + - name: containers + x-displayName: Containers + description: List and manage containers, which are devices running inside containers. - name: sessions - description: Routes related to session resource. + x-displayName: Sessions + description: List and inspect SSH sessions and their recordings. + - name: public-keys + x-displayName: SSH Public Keys + description: Register and manage SSH public keys. + - name: tags + x-displayName: Tags + description: Create tags and attach them to devices. + - name: namespaces + x-displayName: Namespace + description: Inspect the namespace and manage its settings. + - name: stats + x-displayName: Statistics + description: Aggregate statistics for the namespace, such as device and session counts. + - name: firewall + x-displayName: Firewall Rules + description: Manage firewall rules. + - name: tunnels + x-displayName: Tunnels + description: Create and manage device tunnels. + - name: web-endpoints + x-displayName: Web Endpoints + description: Create and manage web endpoints. - name: users - description: Routes related to users resource. - - name: rules - description: Routes related to firewall rules resource + x-displayName: Users + description: User-scoped namespace security settings. + - name: cloud + description: Routes provided by ShellHub Cloud API. - name: announcements description: Routes related to announcements resource - name: mfa @@ -45,10 +73,6 @@ tags: Except for `GET` endpoints, API key-related routes cannot be authenticated with an API key. - - name: tunnels - description: Routes related to tunnels resource. - - name: web-endpoints - description: Routes related to web-endpoints resource. paths: $ref: community-openapi.yaml#/paths @@ -88,8 +112,6 @@ paths: $ref: paths/api@billing@report.yaml /api/billing/evaluate: $ref: paths/api@billing@evaluate.yaml - /api/user/saml/auth: - $ref: paths/api@user@saml@auth.yaml /api/user/mfa/auth: $ref: paths/api@user@mfa@auth.yaml /api/user/mfa/recover: @@ -130,3 +152,54 @@ paths: $ref: paths/api@devices@{uid}@tunnels.yaml /api/devices/{uid}/tunnels/{address}: $ref: paths/api@devices@{uid}@tunnels@{address}.yaml + # Admin (cloud and enterprise) + /admin/api/authentication: + $ref: paths/admin@api@authentication.yaml + /admin/api/authentication/local: + $ref: paths/admin@api@authentication@local.yaml + /admin/api/authentication/saml: + $ref: paths/admin@api@authentication@saml.yaml + /admin/api/devices: + $ref: paths/admin@api@devices.yaml + /admin/api/devices/{uid}: + $ref: paths/admin@api@devices@{uid}.yaml + /admin/api/devices/{uid}/{status}: + $ref: paths/admin@api@devices@{uid}@{status}.yaml + /admin/api/firewall/rules: + $ref: paths/admin@api@firewall@rules.yaml + /admin/api/firewall/rules/{id}: + $ref: paths/admin@api@firewall@rules@{id}.yaml + /admin/api/sessions: + $ref: paths/admin@api@sessions.yaml + /admin/api/sessions/{uid}: + $ref: paths/admin@api@sessions@{uid}.yaml + /admin/api/sshkeys/public-keys: + $ref: paths/admin@api@sshkeys@public-keys.yaml + /admin/api/namespaces: + $ref: paths/admin@api@namespaces.yaml + /admin/api/namespaces/{tenant}: + $ref: paths/admin@api@namespaces@{tenant}.yaml + /admin/api/namespaces-update/{tenantID}: + $ref: paths/admin@api@namespaces-update@{tenantID}.yaml + /admin/api/login: + $ref: paths/admin@api@login.yaml + /admin/api/users: + $ref: paths/admin@api@users.yaml + /admin/api/users/{id}: + $ref: paths/admin@api@users@{id}.yaml + /admin/api/users/{id}/password/reset: + $ref: paths/admin@api@users@{id}@password@reset.yaml + /admin/api/stats: + $ref: paths/admin@api@stats.yaml + /admin/api/license: + $ref: paths/admin@api@license.yaml + /admin/api/auth/token/{id}: + $ref: paths/admin@api@auth@token@{id}.yaml + /admin/api/export/namespaces: + $ref: paths/admin@api@export@namespaces.yaml + /admin/api/export/users: + $ref: paths/admin@api@export@users.yaml + /admin/api/announcements: + $ref: paths/admin@api@announcements.yaml + /admin/api/announcements/{uuid}: + $ref: paths/admin@api@announcements@{uuid}.yaml diff --git a/openapi/spec/community-openapi.yaml b/openapi/spec/community-openapi.yaml index ac4a5245e6e..42b1193774b 100644 --- a/openapi/spec/community-openapi.yaml +++ b/openapi/spec/community-openapi.yaml @@ -2,19 +2,14 @@ openapi: 3.0.3 info: title: ShellHub OpenAPI description: | - > THE API IS NOT STABLE YET; ERROR AND INCONSISTENCIES MAY OCCUR. - - This is the OpenAPI specification for ShellHub community version. It documents the parameters and bodies for - performs HTTP requests to the ShellHub server endpoints related to users, namespaces, members, devices, tags, SSH, - sessions, etc. - - These endpoints require a JSON Web Token (JWT) as its security scheme, that means you need to send, to almost each - request, an HTTP header called `Authorization` with the `bearer` token. To obtains this token, uses the `/api/login` - route, fulfilling its request body to return that token with some essential information about the user whom logged - in. + Full reference for the ShellHub Community API, covering public, internal, + and service-to-service routes. This is the internal source of truth used for + client generation and response validation; the customer-facing documentation + is a filtered build that exposes only the namespace-scoped, API-key usable + surface. contact: - name: ShellHub contact address. - email: contato@ossystems.com.br + name: ShellHub + email: contact@shellhub.io license: name: Apache License 2.0 url: https://github.com/shellhub-io/shellhub/blob/master/LICENSE.md @@ -26,18 +21,36 @@ components: securitySchemes: $ref: ./components/schemas/security.yaml tags: + - name: devices + x-displayName: Devices + description: List, inspect, accept, reject, rename, and delete devices, and manage their custom fields. + - name: containers + x-displayName: Containers + description: List and manage containers, which are devices running inside containers. + - name: sessions + x-displayName: Sessions + description: List and inspect SSH sessions. + - name: public-keys + x-displayName: SSH Public Keys + description: Register and manage SSH public keys. + - name: tags + x-displayName: Tags + description: Create tags and attach them to devices. + - name: namespaces + x-displayName: Namespace + description: Inspect the namespace and manage its settings. + - name: stats + x-displayName: Statistics + description: Aggregate statistics for the namespace, such as device and session counts. + - name: users + x-displayName: Users + description: User-scoped namespace security settings. - name: internal description: Requests executed internally by ShellHub server. - name: external description: Requests executed by the ShellHub user. - - name: users - description: Routes related to user resource. - - name: devices - description: Routes related to device resource. - - name: containers - description: Routes related to containers resource. - - name: ssh - description: Routes related to SSH resource. + - name: system + description: Routes related to running instance. - name: api-keys description: | An API key is a unique identifier used to access protected endpoints. It @@ -51,8 +64,6 @@ tags: Except for `GET` endpoints, API key-related routes cannot be authenticated with an API key. - - name: system - description: Routes related to running instance. paths: /info: @@ -77,8 +88,6 @@ paths: $ref: paths/api@users@{id}@password.yaml /api/users/security/{tenant}: $ref: paths/api@users@security@{tenant}.yaml - /api/users/security: - $ref: paths/api@users@security.yaml /api/devices: $ref: paths/api@devices.yaml /api/devices/{uid}: @@ -91,6 +100,8 @@ paths: $ref: paths/api@devices@{uid}@custom_fields@{key}.yaml /internal/devices/{uid}/offline: $ref: paths/api@devices@{uid}@offline.yaml + /internal/sessions/{uid}: + $ref: paths/internal@sessions@{uid}.yaml /api/sessions: $ref: paths/api@sessions.yaml /api/sessions/{uid}: diff --git a/openapi/spec/components/schemas/namespace.yaml b/openapi/spec/components/schemas/namespace.yaml index 2cabc813ae9..3e87ef7f21b 100644 --- a/openapi/spec/components/schemas/namespace.yaml +++ b/openapi/spec/components/schemas/namespace.yaml @@ -27,6 +27,7 @@ properties: description: Member's email. example: john.doe@test.com settings: + type: object nullable: true allOf: - $ref: namespaceSettings.yaml @@ -41,6 +42,7 @@ properties: format: date-time example: 2020-05-01T00:00:00.000Z billing: + type: object nullable: true allOf: - $ref: namespaceBilling.yaml diff --git a/openapi/spec/components/schemas/security.yaml b/openapi/spec/components/schemas/security.yaml index 856d3f090de..4808bc7a801 100644 --- a/openapi/spec/components/schemas/security.yaml +++ b/openapi/spec/components/schemas/security.yaml @@ -8,5 +8,6 @@ api-key: in: header name: X-API-KEY description: | - An API key is an alternative to the standard JWT authentication. - Authentication with this method is namespace-related and is not tied to any user. + Send your API key in the `X-API-KEY` header. An API key belongs to a single + namespace and is not tied to a user. Create one in the ShellHub console under + **Namespace → API Keys**. diff --git a/openapi/spec/components/schemas/session.yaml b/openapi/spec/components/schemas/session.yaml index 94af9ced1fa..ec2e83508bf 100644 --- a/openapi/spec/components/schemas/session.yaml +++ b/openapi/spec/components/schemas/session.yaml @@ -6,6 +6,7 @@ properties: device_uid: $ref: deviceUID.yaml device: + type: object nullable: true allOf: - $ref: device.yaml diff --git a/openapi/spec/components/schemas/webendpoint.yaml b/openapi/spec/components/schemas/webendpoint.yaml index 1b81535d6cb..de3d2c11233 100644 --- a/openapi/spec/components/schemas/webendpoint.yaml +++ b/openapi/spec/components/schemas/webendpoint.yaml @@ -11,6 +11,7 @@ properties: device_uid: $ref: deviceUID.yaml device: + type: object nullable: true allOf: - $ref: device.yaml diff --git a/openapi/spec/enterprise-openapi.yaml b/openapi/spec/enterprise-openapi.yaml index 33d39133f4e..c9dc60c7f1b 100644 --- a/openapi/spec/enterprise-openapi.yaml +++ b/openapi/spec/enterprise-openapi.yaml @@ -2,13 +2,14 @@ openapi: 3.0.3 info: title: ShellHub Enterprise OpenAPI description: | - > NOTICE: THE API IS NOT STABLE YET; ERROR AND INCONSISTENCIES MAY OCCUR. - - ShellHub Enterprise OpenAPI specification. - - It documents all routes provided by ShellHub Enterprise. + Full reference for the ShellHub Enterprise API, covering public, internal, + and service-to-service routes. This is the internal source of truth used for + client generation and response validation; the customer-facing documentation + is a filtered build that exposes only the namespace-scoped, API-key usable + surface. contact: - email: contato@ossystems.com.br + name: ShellHub + email: contact@shellhub.io license: name: Apache License 2.0 url: https://github.com/shellhub-io/shellhub/blob/master/LICENSE.md @@ -17,27 +18,50 @@ servers: - url: / description: ShellHub server as a Enterprise instance. tags: + - name: devices + x-displayName: Devices + description: List, inspect, accept, reject, rename, and delete devices, and manage their custom fields. + - name: containers + x-displayName: Containers + description: List and manage containers, which are devices running inside containers. + - name: sessions + x-displayName: Sessions + description: List and inspect SSH sessions and their recordings. + - name: public-keys + x-displayName: SSH Public Keys + description: Register and manage SSH public keys. + - name: tags + x-displayName: Tags + description: Create tags and attach them to devices. + - name: namespaces + x-displayName: Namespace + description: Inspect the namespace and manage its settings. + - name: stats + x-displayName: Statistics + description: Aggregate statistics for the namespace, such as device and session counts. + - name: firewall + x-displayName: Firewall Rules + description: Manage firewall rules. + - name: tunnels + x-displayName: Tunnels + description: Create and manage device tunnels. + - name: web-endpoints + x-displayName: Web Endpoints + description: Create and manage web endpoints. + - name: users + x-displayName: Users + description: User-scoped namespace security settings. - name: cloud description: Routes provided by ShellHub Cloud API. - name: authentication-settings description: | Defines the routes to configure and retrieve the ShellHub authentication - settings. Currently, ShellHub supports both local authentication (email + settings. Currently, ShellHub supports both local authentication (email and password) and SAML-based authentication (Single Sign-On). - name: admin description: Routes provide by ShellHub Admin API. - - name: users - description: Routes related to user resource. - - name: stats - description: Routes related to stats resource. - name: license description: Routes related to license resource. - - name: sessions - description: Routes related to session resource. - - name: users - description: Routes related to users resource. - - name: rules - description: Routes related to firewall rules resource. - name: api-keys description: | An API key is a unique identifier used to access protected endpoints. It @@ -51,16 +75,47 @@ tags: Except for `GET` endpoints, API key-related routes cannot be authenticated with an API key. - - name: tunnels - description: Routes related to tunnels resource. - - name: web-endpoints - description: Routes related to web-endpoints resource. components: securitySchemes: $ref: ./components/schemas/security.yaml paths: - $ref: cloud-openapi.yaml#/paths + $ref: community-openapi.yaml#/paths + # Shared surface (cloud and enterprise) + /api/sessions/{uid}/close: + $ref: paths/api@sessions@{uid}@close.yaml + /api/sessions/{uid}/records/{seat}: + $ref: paths/api@sessions@{uid}@records@{seat}.yaml + /api/firewall/rules: + $ref: paths/api@firewall@rules.yaml + /api/firewall/rules/{id}: + $ref: paths/api@firewall@rules@{id}.yaml + /api/user/mfa/auth: + $ref: paths/api@user@mfa@auth.yaml + /api/user/mfa/recover: + $ref: paths/api@user@mfa@recovery.yaml + /api/user/mfa/reset: + $ref: paths/api@user@mfa@reset.yaml + /api/user/mfa/generate: + $ref: paths/api@user@mfa@generate.yaml + /api/user/mfa/enable: + $ref: paths/api@user@mfa@enable.yaml + /api/user/mfa/disable: + $ref: paths/api@user@mfa@disable.yaml + /api/user/mfa/reset/{user-id}: + $ref: paths/api@user@mfa@reset@{user-id}.yaml + /api/web-endpoints: + $ref: paths/api@web-endpoints.yaml + /api/web-endpoints/{address}: + $ref: paths/api@web-endpoints@{address}.yaml + /api/devices/{uid}/tunnels: + $ref: paths/api@devices@{uid}@tunnels.yaml + /api/devices/{uid}/tunnels/{address}: + $ref: paths/api@devices@{uid}@tunnels@{address}.yaml + # Enterprise only + /api/user/saml/auth: + $ref: paths/api@user@saml@auth.yaml + # Admin (cloud and enterprise) /admin/api/authentication: $ref: paths/admin@api@authentication.yaml /admin/api/authentication/local: diff --git a/openapi/spec/openapi.yaml b/openapi/spec/openapi.yaml index fabda5691a8..8d881cb4d8a 100644 --- a/openapi/spec/openapi.yaml +++ b/openapi/spec/openapi.yaml @@ -2,19 +2,12 @@ openapi: 3.0.3 info: title: ShellHub OpenAPI description: | - > THE API IS NOT STABLE YET; ERROR AND INCONSISTENCIES MAY OCCUR. - - This is the OpenAPI specification for ShellHub community version. It documents the parameters and bodies for - performs HTTP requests to the ShellHub server endpoints related to users, namespaces, members, devices, tags, SSH, - sessions, etc. - - These endpoints require a JSON Web Token (JWT) as its security scheme, that means you need to send, to almost each - request, an HTTP header called `Authorization` with the `bearer` token. To obtains this token, uses the `/api/login` - route, fulfilling its request body to return that token with some essential information about the user whom logged - in. + Full OpenAPI specification for ShellHub, covering every edition and surface. + This is the internal reference; the customer-facing documentation is a + filtered build of the per-edition specs. contact: - name: ShellHub contact address. - email: contato@ossystems.com.br + name: ShellHub + email: contact@shellhub.io license: name: Apache License 2.0 url: https://github.com/shellhub-io/shellhub/blob/master/LICENSE.md @@ -83,7 +76,7 @@ tags: description: Routes related to stats resource. - name: license description: Routes related to license resource. - - name: rules + - name: firewall description: Routes related to firewall rules resource. - name: tunnels description: Routes related to tunnels resource. @@ -119,8 +112,6 @@ paths: $ref: paths/api@users@{id}@password.yaml /api/users/security/{tenant}: $ref: paths/api@users@security@{tenant}.yaml - /api/users/security: - $ref: paths/api@users@security.yaml /api/namespaces/device-auto-accept/{tenant}: $ref: paths/api@namespaces@device-auto-accept@{tenant}.yaml /api/devices: @@ -135,6 +126,8 @@ paths: $ref: paths/api@devices@{uid}@custom_fields@{key}.yaml /internal/devices/{uid}/offline: $ref: paths/api@devices@{uid}@offline.yaml + /internal/sessions/{uid}: + $ref: paths/internal@sessions@{uid}.yaml /api/sessions: $ref: paths/api@sessions.yaml /api/sessions/{uid}: diff --git a/openapi/spec/paths/admin@api@firewall@rules.yaml b/openapi/spec/paths/admin@api@firewall@rules.yaml index f210cdeecc8..79bfc98b458 100644 --- a/openapi/spec/paths/admin@api@firewall@rules.yaml +++ b/openapi/spec/paths/admin@api@firewall@rules.yaml @@ -5,7 +5,7 @@ post: tags: - admin - enterprise - - rules + - firewall security: - jwt: [] - api-key: [] @@ -38,7 +38,7 @@ get: tags: - admin - enterprise - - rules + - firewall security: - jwt: [] - api-key: [] diff --git a/openapi/spec/paths/admin@api@firewall@rules@{id}.yaml b/openapi/spec/paths/admin@api@firewall@rules@{id}.yaml index 1048a37a5b7..fdff7133a6c 100644 --- a/openapi/spec/paths/admin@api@firewall@rules@{id}.yaml +++ b/openapi/spec/paths/admin@api@firewall@rules@{id}.yaml @@ -12,7 +12,7 @@ get: tags: - admin - enterprise - - rules + - firewall security: - jwt: [] - api-key: [] @@ -34,7 +34,7 @@ put: tags: - admin - enterprise - - rules + - firewall security: - jwt: [] - api-key: [] @@ -67,7 +67,7 @@ delete: tags: - admin - enterprise - - rules + - firewall security: - jwt: [] - api-key: [] diff --git a/openapi/spec/paths/admin@api@sshkeys@public-keys.yaml b/openapi/spec/paths/admin@api@sshkeys@public-keys.yaml index 37832521427..b5a875a1dc0 100644 --- a/openapi/spec/paths/admin@api@sshkeys@public-keys.yaml +++ b/openapi/spec/paths/admin@api@sshkeys@public-keys.yaml @@ -4,7 +4,7 @@ get: description: Get a list from all public keys. tags: - enterprise - - ssh + - public-keys security: - jwt: [] - api-key: [] @@ -32,7 +32,7 @@ post: description: Create a new public key. tags: - enterprise - - ssh + - public-keys security: - jwt: [] - api-key: [] diff --git a/openapi/spec/paths/api@auth@ssh.yaml b/openapi/spec/paths/api@auth@ssh.yaml index d1428b9e16f..1b8ee43f2f7 100644 --- a/openapi/spec/paths/api@auth@ssh.yaml +++ b/openapi/spec/paths/api@auth@ssh.yaml @@ -4,7 +4,6 @@ post: description: Authenticate a SSH public key to ShellHub server. security: - jwt: [] - - api-key: [] tags: - community - internal diff --git a/openapi/spec/paths/api@auth@token@{tenant}.yaml b/openapi/spec/paths/api@auth@token@{tenant}.yaml index eeaab25ef79..18013be10e3 100644 --- a/openapi/spec/paths/api@auth@token@{tenant}.yaml +++ b/openapi/spec/paths/api@auth@token@{tenant}.yaml @@ -14,7 +14,6 @@ get: - namespaces security: - jwt: [] - - api-key: [] parameters: - $ref: ../components/parameters/path/namespaceTenantIDPath.yaml responses: diff --git a/openapi/spec/paths/api@auth@user.yaml b/openapi/spec/paths/api@auth@user.yaml index daec1f617fe..2f52b793ca3 100644 --- a/openapi/spec/paths/api@auth@user.yaml +++ b/openapi/spec/paths/api@auth@user.yaml @@ -45,7 +45,6 @@ get: - users security: - jwt: [] - - api-key: [] responses: '200': description: Success to get the user info. diff --git a/openapi/spec/paths/api@billing@customer.yaml b/openapi/spec/paths/api@billing@customer.yaml index bbeb1da3bd8..558ab5bef2a 100644 --- a/openapi/spec/paths/api@billing@customer.yaml +++ b/openapi/spec/paths/api@billing@customer.yaml @@ -4,7 +4,6 @@ post: description: creates a new customer defining, optionaly, the default payment method. security: - jwt: [] - - api-key: [] tags: - cloud - billing @@ -31,7 +30,6 @@ get: description: Get the customer. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@device-choice.yaml b/openapi/spec/paths/api@billing@device-choice.yaml index b210328a5e2..acdf16c73c7 100644 --- a/openapi/spec/paths/api@billing@device-choice.yaml +++ b/openapi/spec/paths/api@billing@device-choice.yaml @@ -4,7 +4,6 @@ post: description: Choice devices when device's limit is rechead. security: - jwt: [] - - api-key: [] tags: - cloud diff --git a/openapi/spec/paths/api@billing@devices-most-used.yaml b/openapi/spec/paths/api@billing@devices-most-used.yaml index ae303d57cc9..235940ba1a0 100644 --- a/openapi/spec/paths/api@billing@devices-most-used.yaml +++ b/openapi/spec/paths/api@billing@devices-most-used.yaml @@ -4,7 +4,6 @@ get: description: Get the most used devices. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@evaluate.yaml b/openapi/spec/paths/api@billing@evaluate.yaml index 1e6d29f32a0..ec0962381f2 100644 --- a/openapi/spec/paths/api@billing@evaluate.yaml +++ b/openapi/spec/paths/api@billing@evaluate.yaml @@ -4,7 +4,6 @@ post: description: evaluate the namespace capabilities. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@paymentmethod@attach.yaml b/openapi/spec/paths/api@billing@paymentmethod@attach.yaml index ba9f4d4131f..fdfc5b01b5f 100644 --- a/openapi/spec/paths/api@billing@paymentmethod@attach.yaml +++ b/openapi/spec/paths/api@billing@paymentmethod@attach.yaml @@ -4,7 +4,6 @@ post: description: Attachs a payment method to a customer. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@paymentmethod@default.yaml b/openapi/spec/paths/api@billing@paymentmethod@default.yaml index 5c9fb33f891..7684fece451 100644 --- a/openapi/spec/paths/api@billing@paymentmethod@default.yaml +++ b/openapi/spec/paths/api@billing@paymentmethod@default.yaml @@ -4,7 +4,6 @@ post: description: Set default payment method to the customer. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@paymentmethod@detach.yaml b/openapi/spec/paths/api@billing@paymentmethod@detach.yaml index 3f67ad72c1f..42fdcb15b95 100644 --- a/openapi/spec/paths/api@billing@paymentmethod@detach.yaml +++ b/openapi/spec/paths/api@billing@paymentmethod@detach.yaml @@ -4,7 +4,6 @@ post: description: Detachs a payment method from a customer. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@report.yaml b/openapi/spec/paths/api@billing@report.yaml index 22b9c8a334a..ca33cf98c12 100644 --- a/openapi/spec/paths/api@billing@report.yaml +++ b/openapi/spec/paths/api@billing@report.yaml @@ -4,7 +4,6 @@ post: description: Report an action. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@subscription.yaml b/openapi/spec/paths/api@billing@subscription.yaml index 5aeaf5f9c94..8dad483deed 100644 --- a/openapi/spec/paths/api@billing@subscription.yaml +++ b/openapi/spec/paths/api@billing@subscription.yaml @@ -4,7 +4,6 @@ post: description: Create a subscription. security: - jwt: [] - - api-key: [] tags: - cloud - billing @@ -31,7 +30,6 @@ get: description: Get the subscription. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@billing@{id}@payment-method.yaml b/openapi/spec/paths/api@billing@{id}@payment-method.yaml index abc81f220ef..1375aa75f00 100644 --- a/openapi/spec/paths/api@billing@{id}@payment-method.yaml +++ b/openapi/spec/paths/api@billing@{id}@payment-method.yaml @@ -11,7 +11,6 @@ post: description: Add a new payment method. security: - jwt: [] - - api-key: [] tags: - cloud - billing @@ -70,7 +69,6 @@ patch: description: Update the payment method. security: - jwt: [] - - api-key: [] tags: - cloud - billing @@ -114,7 +112,6 @@ delete: description: Deattach a payment method. security: - jwt: [] - - api-key: [] tags: - cloud - billing diff --git a/openapi/spec/paths/api@containers.yaml b/openapi/spec/paths/api@containers.yaml index 56e671655af..ec4ce0b3ee3 100644 --- a/openapi/spec/paths/api@containers.yaml +++ b/openapi/spec/paths/api@containers.yaml @@ -1,7 +1,7 @@ get: operationId: getContainers - summary: Get containers - description: Get a list of containers. + summary: List containers + description: List containers. tags: - community - containers diff --git a/openapi/spec/paths/api@containers@{uid}.yaml b/openapi/spec/paths/api@containers@{uid}.yaml index 66290402da9..bb43f7f2011 100644 --- a/openapi/spec/paths/api@containers@{uid}.yaml +++ b/openapi/spec/paths/api@containers@{uid}.yaml @@ -2,7 +2,7 @@ parameters: - $ref: ../components/parameters/path/deviceUIDPath.yaml get: operationId: getContainer - summary: Get container + summary: Get a container description: Get a container. tags: - community @@ -25,7 +25,7 @@ get: $ref: ../components/responses/500.yaml delete: operationId: deleteContainer - summary: Delete container + summary: Delete a container description: Delete a container. tags: - community @@ -44,8 +44,8 @@ delete: $ref: ../components/responses/500.yaml put: operationId: updateContainer - summary: Update container - description: Update container's data. + summary: Update a container + description: Update a container. tags: - community - containers diff --git a/openapi/spec/paths/api@containers@{uid}@tags@{name}.yaml b/openapi/spec/paths/api@containers@{uid}@tags@{name}.yaml index 7a1ba560524..50f41340255 100644 --- a/openapi/spec/paths/api@containers@{uid}@tags@{name}.yaml +++ b/openapi/spec/paths/api@containers@{uid}@tags@{name}.yaml @@ -1,7 +1,7 @@ post: operationId: pushTagToContainer - summary: Associate a tag with a container - description: Associates a tag with a container in the authenticated namespace. + summary: Add a tag to a container + description: Add a tag to a container. tags: - community - tags @@ -27,7 +27,7 @@ post: delete: operationId: pullTagFromContainer summary: Remove a tag from a container - description: Removes a tag from a container in the authenticated namespace. + description: Remove a tag from a container. tags: - community - tags diff --git a/openapi/spec/paths/api@containers@{uid}@{status}.yaml b/openapi/spec/paths/api@containers@{uid}@{status}.yaml index d7f6077ff4b..eba4b4cb496 100644 --- a/openapi/spec/paths/api@containers@{uid}@{status}.yaml +++ b/openapi/spec/paths/api@containers@{uid}@{status}.yaml @@ -1,7 +1,7 @@ patch: operationId: updateContainerStatus - summary: Update container status - description: Update container's status. + summary: Update a container's status + description: Update a container's status. tags: - community - containers diff --git a/openapi/spec/paths/api@devices.yaml b/openapi/spec/paths/api@devices.yaml index 43d5c6b8e05..5600359ecd7 100644 --- a/openapi/spec/paths/api@devices.yaml +++ b/openapi/spec/paths/api@devices.yaml @@ -1,7 +1,7 @@ get: operationId: getDevices - summary: Get devices - description: Get a list of devices. + summary: List devices + description: List devices. tags: - community - devices diff --git a/openapi/spec/paths/api@devices@resolve.yaml b/openapi/spec/paths/api@devices@resolve.yaml index 17493e1cfe1..dba4b0f5fe2 100644 --- a/openapi/spec/paths/api@devices@resolve.yaml +++ b/openapi/spec/paths/api@devices@resolve.yaml @@ -1,13 +1,9 @@ get: operationId: resolveDevice - summary: Resolve Device + summary: Resolve a device description: | - Retrieve a device using flexible resolution methods. The device can be - identified by either its unique identifier (UID) or hostname. The endpoint - automatically scopes results to the authenticated tenant's namespace for - security isolation. - - When both UID and hostname are provided, UID takes precedence over hostname. + Resolve a device by UID or hostname. If both are provided, UID takes + precedence. tags: - community - devices diff --git a/openapi/spec/paths/api@devices@{uid}.yaml b/openapi/spec/paths/api@devices@{uid}.yaml index b76ecf3ee77..d1281f9de3b 100644 --- a/openapi/spec/paths/api@devices@{uid}.yaml +++ b/openapi/spec/paths/api@devices@{uid}.yaml @@ -2,7 +2,7 @@ parameters: - $ref: ../components/parameters/path/deviceUIDPath.yaml get: operationId: getDevice - summary: Get device + summary: Get a device description: Get a device. tags: - community @@ -25,7 +25,7 @@ get: $ref: ../components/responses/500.yaml delete: operationId: deleteDevice - summary: Delete device + summary: Delete a device description: Delete a device. tags: - community @@ -44,8 +44,8 @@ delete: $ref: ../components/responses/500.yaml put: operationId: updateDevice - summary: Update device - description: Update device's data. + summary: Update a device + description: Update a device. tags: - community - devices diff --git a/openapi/spec/paths/api@devices@{uid}@accept.yaml b/openapi/spec/paths/api@devices@{uid}@accept.yaml index 3ed35204283..c0c4b0605de 100644 --- a/openapi/spec/paths/api@devices@{uid}@accept.yaml +++ b/openapi/spec/paths/api@devices@{uid}@accept.yaml @@ -1,7 +1,7 @@ patch: operationId: acceptDevice - summary: Accept device - description: Change device status to `accepted`. + summary: Accept a device + description: Accept a pending device. tags: - community - devices diff --git a/openapi/spec/paths/api@devices@{uid}@offline.yaml b/openapi/spec/paths/api@devices@{uid}@offline.yaml index 943c2ab9a6b..41d121cbbfe 100644 --- a/openapi/spec/paths/api@devices@{uid}@offline.yaml +++ b/openapi/spec/paths/api@devices@{uid}@offline.yaml @@ -8,7 +8,6 @@ post: - internal security: - jwt: [] - - api-key: [] parameters: - $ref: ../components/parameters/path/deviceUIDPath.yaml responses: diff --git a/openapi/spec/paths/api@devices@{uid}@tags@{name}.yaml b/openapi/spec/paths/api@devices@{uid}@tags@{name}.yaml index 03fcb291a8a..879396352d8 100644 --- a/openapi/spec/paths/api@devices@{uid}@tags@{name}.yaml +++ b/openapi/spec/paths/api@devices@{uid}@tags@{name}.yaml @@ -1,7 +1,7 @@ post: operationId: pushTagToDevice - summary: Associate a tag with a device - description: Associates a tag with a device in the authenticated namespace. + summary: Add a tag to a device + description: Add a tag to a device. tags: - community - tags @@ -27,7 +27,7 @@ post: delete: operationId: pullTagFromDevice summary: Remove a tag from a device - description: Removes a tag from a device in the authenticated namespace. + description: Remove a tag from a device. tags: - community - tags diff --git a/openapi/spec/paths/api@devices@{uid}@tunnels.yaml b/openapi/spec/paths/api@devices@{uid}@tunnels.yaml index b54630672fa..1e9dcf6eaf6 100644 --- a/openapi/spec/paths/api@devices@{uid}@tunnels.yaml +++ b/openapi/spec/paths/api@devices@{uid}@tunnels.yaml @@ -2,8 +2,8 @@ parameters: - $ref: ../components/parameters/path/deviceUIDPath.yaml get: operationId: listTunnels - summary: List tunnels - description: List the tunnels per devices. + summary: List device tunnels + description: List device tunnels. deprecated: true tags: - cloud @@ -37,8 +37,8 @@ get: $ref: ../components/responses/500.yaml post: operationId: createTunnel - summary: Create a tunnel - description: Creates a new tunnel for a device. + summary: Create a device tunnel + description: Create a device tunnel. deprecated: true tags: - cloud diff --git a/openapi/spec/paths/api@devices@{uid}@tunnels@{address}.yaml b/openapi/spec/paths/api@devices@{uid}@tunnels@{address}.yaml index e1aad28ec65..b754f83376d 100644 --- a/openapi/spec/paths/api@devices@{uid}@tunnels@{address}.yaml +++ b/openapi/spec/paths/api@devices@{uid}@tunnels@{address}.yaml @@ -4,7 +4,7 @@ parameters: delete: operationId: deleteTunnel summary: Delete a tunnel - description: Deletes a tunnel for a specific device and port. + description: Delete a device tunnel. deprecated: true tags: - cloud diff --git a/openapi/spec/paths/api@devices@{uid}@{status}.yaml b/openapi/spec/paths/api@devices@{uid}@{status}.yaml index bed3b3bdebd..efbeb431627 100644 --- a/openapi/spec/paths/api@devices@{uid}@{status}.yaml +++ b/openapi/spec/paths/api@devices@{uid}@{status}.yaml @@ -1,7 +1,7 @@ patch: operationId: updateDeviceStatus - summary: Update device status - description: Update device's status. + summary: Update a device's status + description: Update a device's status. tags: - community - devices diff --git a/openapi/spec/paths/api@firewall@rules.yaml b/openapi/spec/paths/api@firewall@rules.yaml index 4a0f349cf32..4616ce290b4 100644 --- a/openapi/spec/paths/api@firewall@rules.yaml +++ b/openapi/spec/paths/api@firewall@rules.yaml @@ -1,11 +1,11 @@ post: operationId: createFirewallRule - summary: Create firewall rule + summary: Create a firewall rule description: Create a firewall rule. tags: - cloud - - rules + - firewall security: - jwt: [] - api-key: [] @@ -33,12 +33,12 @@ post: $ref: ../components/responses/500.yaml get: operationId: getFirewallRules - summary: Get firewall rules - description: Get a list of firewall rules. + summary: List firewall rules + description: List firewall rules. tags: - cloud - - rules + - firewall security: - jwt: [] - api-key: [] diff --git a/openapi/spec/paths/api@firewall@rules@{id}.yaml b/openapi/spec/paths/api@firewall@rules@{id}.yaml index 5931266058a..7156019574d 100644 --- a/openapi/spec/paths/api@firewall@rules@{id}.yaml +++ b/openapi/spec/paths/api@firewall@rules@{id}.yaml @@ -7,11 +7,11 @@ parameters: required: true get: operationId: getFirewallRule - summary: Get firewall rule + summary: Get a firewall rule description: Get a firewall rule. tags: - cloud - - rules + - firewall security: - jwt: [] - api-key: [] @@ -28,11 +28,11 @@ get: $ref: ../components/responses/500.yaml put: operationId: updateFirewallRule - summary: Update firewall rule + summary: Update a firewall rule description: Update a firewall rule. tags: - cloud - - rules + - firewall security: - jwt: [] - api-key: [] @@ -60,11 +60,11 @@ put: $ref: ../components/responses/500.yaml delete: operationId: deleteFirewallRule - summary: Delete firewall rule + summary: Delete a firewall rule description: Delete a firewall rule. tags: - cloud - - rules + - firewall security: - jwt: [] - api-key: [] diff --git a/openapi/spec/paths/api@healthcheck.yaml b/openapi/spec/paths/api@healthcheck.yaml index 961c63120c5..22fd445a746 100644 --- a/openapi/spec/paths/api@healthcheck.yaml +++ b/openapi/spec/paths/api@healthcheck.yaml @@ -10,6 +10,7 @@ get: - cloud - enterprise - system + security: [] responses: '200': description: Service is healthy and responding diff --git a/openapi/spec/paths/api@namespaces.yaml b/openapi/spec/paths/api@namespaces.yaml index 5e702e577e6..42718698fec 100644 --- a/openapi/spec/paths/api@namespaces.yaml +++ b/openapi/spec/paths/api@namespaces.yaml @@ -1,5 +1,6 @@ get: operationId: getNamespaces + x-internal: true summary: Get namespaces list description: Returns a list of namespaces. tags: @@ -61,6 +62,7 @@ get: $ref: ../components/responses/500.yaml post: operationId: createNamespace + x-internal: true summary: Create namespace description: Create a namespace. tags: diff --git a/openapi/spec/paths/api@namespaces@api-key.yaml b/openapi/spec/paths/api@namespaces@api-key.yaml index 3e5bfce11de..bb4ed5520ec 100644 --- a/openapi/spec/paths/api@namespaces@api-key.yaml +++ b/openapi/spec/paths/api@namespaces@api-key.yaml @@ -34,6 +34,7 @@ post: $ref: ../components/responses/500.yaml get: operationId: apiKeyList + x-internal: true summary: List API Keys tags: - api-keys @@ -42,7 +43,6 @@ get: security: - jwt: [] - api-key: [] - - api-key: [] parameters: - $ref: ../components/parameters/query/pageQuery.yaml - $ref: ../components/parameters/query/perPageQuery.yaml diff --git a/openapi/spec/paths/api@namespaces@{tenant}.yaml b/openapi/spec/paths/api@namespaces@{tenant}.yaml index 7675d80dbf4..5356a045fe7 100644 --- a/openapi/spec/paths/api@namespaces@{tenant}.yaml +++ b/openapi/spec/paths/api@namespaces@{tenant}.yaml @@ -2,8 +2,8 @@ parameters: - $ref: ../components/parameters/path/namespaceTenantIDPath.yaml get: operationId: getNamespace - summary: Get a namespace - description: Get a namespace. + summary: Get the current namespace + description: Get the current namespace. tags: - community - namespaces @@ -27,8 +27,8 @@ get: $ref: ../components/responses/500.yaml put: operationId: editNamespace - summary: Edit namespace - description: Edit a namespace. + summary: Update the current namespace + description: Update the current namespace. tags: - community - namespaces @@ -66,14 +66,13 @@ put: $ref: ../components/responses/500.yaml delete: operationId: deleteNamespace - summary: Delete namespace - description: Delete a namespace. + summary: Delete the current namespace + description: Delete the current namespace. tags: - community - namespaces security: - jwt: [] - - api-key: [] responses: '200': description: Success to delete a namespace. diff --git a/openapi/spec/paths/api@namespaces@{tenant}@containers@{uid}@tags@{name}.yaml b/openapi/spec/paths/api@namespaces@{tenant}@containers@{uid}@tags@{name}.yaml index 507fd0cabb1..403aef37e50 100644 --- a/openapi/spec/paths/api@namespaces@{tenant}@containers@{uid}@tags@{name}.yaml +++ b/openapi/spec/paths/api@namespaces@{tenant}@containers@{uid}@tags@{name}.yaml @@ -1,7 +1,7 @@ post: operationId: pushTagToContainerDeprecated deprecated: true - summary: Associate a tag with a container + summary: Add a tag to a container description: '**Deprecated**: Use `POST /api/containers/{uid}/tags/{name}` instead.' tags: - community diff --git a/openapi/spec/paths/api@namespaces@{tenant}@devices@{uid}@tags@{name}.yaml b/openapi/spec/paths/api@namespaces@{tenant}@devices@{uid}@tags@{name}.yaml index 0af03193907..fab70194132 100644 --- a/openapi/spec/paths/api@namespaces@{tenant}@devices@{uid}@tags@{name}.yaml +++ b/openapi/spec/paths/api@namespaces@{tenant}@devices@{uid}@tags@{name}.yaml @@ -1,7 +1,7 @@ post: operationId: pushTagToDeviceDeprecated deprecated: true - summary: Associate a tag with a device + summary: Add a tag to a device description: '**Deprecated**: Use `POST /api/devices/{uid}/tags/{name}` instead.' tags: - community diff --git a/openapi/spec/paths/api@namespaces@{tenant}@members.yaml b/openapi/spec/paths/api@namespaces@{tenant}@members.yaml index 1774d089ece..2b4e8e88cce 100644 --- a/openapi/spec/paths/api@namespaces@{tenant}@members.yaml +++ b/openapi/spec/paths/api@namespaces@{tenant}@members.yaml @@ -1,5 +1,6 @@ delete: operationId: leaveNamespace + x-internal: true summary: Leave Namespace description: | Allows the authenticated user to leave the specified namespace. Owners diff --git a/openapi/spec/paths/api@namespaces@{tenant}@members@{id}@accept-invite.yaml b/openapi/spec/paths/api@namespaces@{tenant}@members@{id}@accept-invite.yaml index 15be00392dd..32631a08d33 100644 --- a/openapi/spec/paths/api@namespaces@{tenant}@members@{id}@accept-invite.yaml +++ b/openapi/spec/paths/api@namespaces@{tenant}@members@{id}@accept-invite.yaml @@ -9,6 +9,7 @@ get: - namespaces - members - namespaces + security: [] parameters: - name: tenant in: path diff --git a/openapi/spec/paths/api@namespaces@{tenant}@tags.yaml b/openapi/spec/paths/api@namespaces@{tenant}@tags.yaml index 25d491db214..0b829b027ea 100644 --- a/openapi/spec/paths/api@namespaces@{tenant}@tags.yaml +++ b/openapi/spec/paths/api@namespaces@{tenant}@tags.yaml @@ -1,7 +1,7 @@ get: operationId: getTagsDeprecated deprecated: true - summary: Retrieve all tags associated with a namespace + summary: List tags description: '**Deprecated**: Use `GET /api/tags` instead.' tags: - community @@ -37,8 +37,8 @@ get: post: operationId: createTagDeprecated deprecated: true - summary: Create a new tag in the namespace - description: '**Deprecated**: Use `POST /api/tags` instead. Creates a tag that can be later associated with content. Tag names must be unique within the namespace.' + summary: Create a tag + description: '**Deprecated**: Use `POST /api/tags` instead. Tag names must be unique.' tags: - community - tags diff --git a/openapi/spec/paths/api@sessions.yaml b/openapi/spec/paths/api@sessions.yaml index 4523c31c6db..8c159f4a399 100644 --- a/openapi/spec/paths/api@sessions.yaml +++ b/openapi/spec/paths/api@sessions.yaml @@ -1,7 +1,7 @@ get: operationId: getSessions - summary: Get sessions - description: Get a list sessions. + summary: List sessions + description: List sessions. tags: - community - sessions diff --git a/openapi/spec/paths/api@sessions@{uid}.yaml b/openapi/spec/paths/api@sessions@{uid}.yaml index bce7f0e6f5f..661516bdfbe 100644 --- a/openapi/spec/paths/api@sessions@{uid}.yaml +++ b/openapi/spec/paths/api@sessions@{uid}.yaml @@ -2,7 +2,7 @@ parameters: - $ref: ../components/parameters/path/sessionUIDPath.yaml get: operationId: getSession - summary: Get session + summary: Get a session description: Get a session. tags: - community @@ -21,29 +21,3 @@ get: $ref: ../components/responses/401.yaml '500': $ref: ../components/responses/500.yaml -post: - operationId: setSessionAuthenticationStatus - summary: Set session authentication status - description: Set session authentication status. - tags: - - community - - sessions - security: - - jwt: [] - - api-key: [] - requestBody: - content: - application/json: - schema: - type: object - properties: - authenticated: - description: Session's authentication status. - type: boolean - responses: - '200': - $ref: ../components/responses/200.yaml - '401': - $ref: ../components/responses/401.yaml - '500': - $ref: ../components/responses/500.yaml diff --git a/openapi/spec/paths/api@sshkeys@public-keys.yaml b/openapi/spec/paths/api@sshkeys@public-keys.yaml index adebff62d7b..90a0065a4f8 100644 --- a/openapi/spec/paths/api@sshkeys@public-keys.yaml +++ b/openapi/spec/paths/api@sshkeys@public-keys.yaml @@ -1,10 +1,10 @@ get: operationId: getPublicKeys - summary: Get public keys - description: Get a list from all public keys. + summary: List SSH public keys + description: List SSH public keys. tags: - community - - ssh + - public-keys security: - jwt: [] - api-key: [] @@ -30,13 +30,14 @@ get: $ref: ../components/responses/500.yaml post: operationId: createPublicKey - summary: Create public key - description: Create a new public key. + summary: Create an SSH public key + description: Create an SSH public key. tags: - community - - ssh + - public-keys security: - jwt: [] + - api-key: [] requestBody: content: application/json: diff --git a/openapi/spec/paths/api@sshkeys@public-keys@{fingerprint}.yaml b/openapi/spec/paths/api@sshkeys@public-keys@{fingerprint}.yaml index f019f975bf3..f21012022c5 100644 --- a/openapi/spec/paths/api@sshkeys@public-keys@{fingerprint}.yaml +++ b/openapi/spec/paths/api@sshkeys@public-keys@{fingerprint}.yaml @@ -2,13 +2,14 @@ parameters: - $ref: ../components/parameters/path/publicKeyFingerprintPath.yaml put: operationId: updatePublicKey - summary: Update public key - description: Update a public key. + summary: Update an SSH public key + description: Update an SSH public key. tags: - community - - ssh + - public-keys security: - jwt: [] + - api-key: [] requestBody: content: application/json: @@ -48,13 +49,14 @@ put: $ref: ../components/responses/500.yaml delete: operationId: deletePublicKey - summary: Delete public key - description: Delete a public key. + summary: Delete an SSH public key + description: Delete an SSH public key. tags: - community - - ssh + - public-keys security: - jwt: [] + - api-key: [] responses: '200': description: Success to delete a public key. diff --git a/openapi/spec/paths/api@stats.yaml b/openapi/spec/paths/api@stats.yaml index ac54cc7a3ac..49f6a553a6f 100644 --- a/openapi/spec/paths/api@stats.yaml +++ b/openapi/spec/paths/api@stats.yaml @@ -1,10 +1,10 @@ get: operationId: getStatusDevices - summary: Get stats ShellHub instance - description: Get stats ShellHub instance. + summary: Get namespace statistics + description: Get namespace statistics. tags: - community - - devices + - stats security: - jwt: [] - api-key: [] diff --git a/openapi/spec/paths/api@tags.yaml b/openapi/spec/paths/api@tags.yaml index 2c928024a6b..a2641a60548 100644 --- a/openapi/spec/paths/api@tags.yaml +++ b/openapi/spec/paths/api@tags.yaml @@ -1,7 +1,7 @@ get: operationId: getTags - summary: Retrieve all tags associated with the namespace - description: Retrieves all tags for the authenticated namespace. + summary: List tags + description: List all tags. tags: - community - tags @@ -34,8 +34,8 @@ get: $ref: ../components/responses/500.yaml post: operationId: createTag - summary: Create a new tag in the namespace - description: Creates a tag in the authenticated namespace that can be later associated with content. Tag names must be unique within the namespace. + summary: Create a tag + description: Create a tag. Tag names must be unique. tags: - community - tags diff --git a/openapi/spec/paths/api@tags@{name}.yaml b/openapi/spec/paths/api@tags@{name}.yaml index 555cec7f5c6..919e4ba8db6 100644 --- a/openapi/spec/paths/api@tags@{name}.yaml +++ b/openapi/spec/paths/api@tags@{name}.yaml @@ -1,7 +1,7 @@ patch: operationId: updateTag summary: Update a tag - description: Updates a tag in the authenticated namespace. + description: Update a tag. tags: - community - tags @@ -43,7 +43,7 @@ patch: delete: operationId: deleteTag summary: Delete a tag - description: Removes a tag and all its associations from the authenticated namespace. + description: Delete a tag and remove it from all devices and containers. tags: - community - tags diff --git a/openapi/spec/paths/api@user@mfa@auth.yaml b/openapi/spec/paths/api@user@mfa@auth.yaml index 88bb546f23b..d4f497c008c 100644 --- a/openapi/spec/paths/api@user@mfa@auth.yaml +++ b/openapi/spec/paths/api@user@mfa@auth.yaml @@ -8,6 +8,7 @@ post: - cloud - mfa - users + security: [] requestBody: content: application/json: diff --git a/openapi/spec/paths/api@user@mfa@recovery.yaml b/openapi/spec/paths/api@user@mfa@recovery.yaml index 855fbf14243..7845f5cae41 100644 --- a/openapi/spec/paths/api@user@mfa@recovery.yaml +++ b/openapi/spec/paths/api@user@mfa@recovery.yaml @@ -13,6 +13,7 @@ post: - cloud - mfa - users + security: [] requestBody: content: application/json: diff --git a/openapi/spec/paths/api@user@mfa@reset.yaml b/openapi/spec/paths/api@user@mfa@reset.yaml index 03a5c2ee51e..245b173ef12 100644 --- a/openapi/spec/paths/api@user@mfa@reset.yaml +++ b/openapi/spec/paths/api@user@mfa@reset.yaml @@ -9,6 +9,7 @@ post: - cloud - mfa - users + security: [] requestBody: content: application/json: diff --git a/openapi/spec/paths/api@user@mfa@reset@{user-id}.yaml b/openapi/spec/paths/api@user@mfa@reset@{user-id}.yaml index 40f1deb50e1..826cc9f3109 100644 --- a/openapi/spec/paths/api@user@mfa@reset@{user-id}.yaml +++ b/openapi/spec/paths/api@user@mfa@reset@{user-id}.yaml @@ -9,6 +9,7 @@ put: - cloud - mfa - users + security: [] parameters: - in: path name: user-id diff --git a/openapi/spec/paths/api@users@security.yaml b/openapi/spec/paths/api@users@security.yaml deleted file mode 100644 index 20ed24f56a4..00000000000 --- a/openapi/spec/paths/api@users@security.yaml +++ /dev/null @@ -1,25 +0,0 @@ -get: - operationId: checkSessionRecord - summary: Check session record status - description: Check status from if `session record` feature is enable. - tags: - - community - - sessions - - users - security: - - jwt: [] - - api-key: [] - responses: - '200': - description: Success get session record status - content: - application/json: - schema: - description: Session record status - type: boolean - '401': - $ref: ../components/responses/401.yaml - '404': - $ref: ../components/responses/404.yaml - '500': - $ref: ../components/responses/500.yaml diff --git a/openapi/spec/paths/api@web-endpoints.yaml b/openapi/spec/paths/api@web-endpoints.yaml index d1afba40bff..6387c5d75b0 100644 --- a/openapi/spec/paths/api@web-endpoints.yaml +++ b/openapi/spec/paths/api@web-endpoints.yaml @@ -1,7 +1,7 @@ get: operationId: listWebEndpoints - summary: List web-endpoints - description: List all web-endpoints in the namespace. + summary: List web endpoints + description: List web endpoints. tags: - cloud - web-endpoints @@ -45,8 +45,8 @@ get: $ref: ../components/responses/500.yaml post: operationId: createWebEndpoint - summary: Create a web-endpoint - description: Creates a new web-endpoint for a device. + summary: Create a web endpoint + description: Create a web endpoint for a device. tags: - cloud - web-endpoints diff --git a/openapi/spec/paths/api@web-endpoints@{address}.yaml b/openapi/spec/paths/api@web-endpoints@{address}.yaml index 7117851ace5..c3f4e7dc39a 100644 --- a/openapi/spec/paths/api@web-endpoints@{address}.yaml +++ b/openapi/spec/paths/api@web-endpoints@{address}.yaml @@ -2,8 +2,8 @@ parameters: - $ref: ../components/parameters/path/tunnelAddressPath.yaml delete: operationId: deleteWebEndpoint - summary: Delete a web-endpoint - description: Deletes a web-endpoint by address. + summary: Delete a web endpoint + description: Delete a web endpoint. tags: - cloud - web-endpoints diff --git a/openapi/spec/paths/internal@sessions@{uid}.yaml b/openapi/spec/paths/internal@sessions@{uid}.yaml new file mode 100644 index 00000000000..9b231bac5e0 --- /dev/null +++ b/openapi/spec/paths/internal@sessions@{uid}.yaml @@ -0,0 +1,30 @@ +parameters: + - $ref: ../components/parameters/path/sessionUIDPath.yaml +patch: + operationId: setSessionAuthenticationStatus + summary: Set session authentication status + description: | + Internal route used by the SSH service to set a session's authentication + status (UpdateSession). + tags: + - community + - sessions + - internal + security: + - jwt: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + authenticated: + description: Session's authentication status. + type: boolean + responses: + '200': + $ref: ../components/responses/200.yaml + '401': + $ref: ../components/responses/401.yaml + '500': + $ref: ../components/responses/500.yaml diff --git a/openapi/static/customer.html b/openapi/static/customer.html new file mode 100644 index 00000000000..ac1ea2fd420 --- /dev/null +++ b/openapi/static/customer.html @@ -0,0 +1,27 @@ + + + + ShellHub API (customer preview) + + + + + + + + + + + + + diff --git a/ui-react/Dockerfile b/ui-react/Dockerfile index 4bf4ed6d9f2..c60d68cb480 100644 --- a/ui-react/Dockerfile +++ b/ui-react/Dockerfile @@ -28,9 +28,10 @@ CMD ["/scripts/entrypoint-dev.sh"] # Bundle OpenAPI spec from YAML sources FROM node:24.16.0-alpine3.22 AS spec-bundler -RUN npm install -g @redocly/cli@1.0.0-beta.100 +RUN npm install -g @redocly/cli@2.31.5 WORKDIR /spec COPY openapi/spec ./spec +COPY openapi/plugins ./plugins COPY openapi/redocly.yaml . RUN redocly bundle spec/openapi.yaml -o openapi.json diff --git a/ui-react/scripts/generate-client.sh b/ui-react/scripts/generate-client.sh index 71f84e80eb0..a474e93f23c 100755 --- a/ui-react/scripts/generate-client.sh +++ b/ui-react/scripts/generate-client.sh @@ -5,7 +5,7 @@ set -e # client. The Dockerfile builder stage sets OPENAPI_SPEC_PATH to a spec # it bundled in an earlier stage; skip the bundle step in that case. if [ -z "$OPENAPI_SPEC_PATH" ]; then - npx @redocly/cli@1.0.0-beta.100 bundle /openapi/spec/openapi.yaml -o /tmp/openapi.json --force + npx @redocly/cli@2.31.5 bundle /openapi/spec/openapi.yaml -o /tmp/openapi.json --force OPENAPI_SPEC_PATH=/tmp/openapi.json export OPENAPI_SPEC_PATH fi