docs(api): add console sm admin api

[urbanisierung]

Description

• Relates https://github.com/camunda-cloud/camunda-cloud-management-apps/issues/2871
• Uses interactive api explorer

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @christinaausley as a reviewer.

[github-actions]

👋 🤖 🤔 Hello! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.5/.

• docs/apis-tools/console-sm-api/console-sm-api-authentication.md
• docs/apis-tools/console-sm-api/console-sm-api-overview.md
• docs/apis-tools/console-sm-api/sidebar-schema.js
• docs/apis-tools/console-sm-api/specifications/console-sm-admin-api.info.mdx
• docs/apis-tools/console-sm-api/specifications/get-clusters.api.mdx
• docs/apis-tools/console-sm-api/specifications/get-usage-metrics.api.mdx
• docs/apis-tools/console-sm-api/specifications/sidebar.js

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[urbanisierung]

@theburi @ultraschuppi Here's the Docs PR for the Console SM Admin API. It uses the interactive API explorer generated from our OpenAPI spec. Please have a look and review the changes.

[urbanisierung]

@pepopowitz iirc you've introduced the interactive API explorer to the docs. Can you please have a quick look if anything is missing in this PR? Thanks!

[pepopowitz]

This is really fantastic!!!

I have a couple small blocking requests, and one non-blocking. Overall, it's great, and I want to thank you for following the patterns in place and practically nailing this implementation. It looks really good.

I'm also curious if you have feedback for me on what it takes to add a new API Explorer. Were there challenges along the way that seemed frustrating or unnecessary? Any opportunities for improvement you noticed?

[pepopowitz]

Thanks for cleaning this up!

[urbanisierung]

I'm also curious if you have feedback for me on what it takes to add a new API Explorer. Were there challenges along the way that seemed frustrating or unnecessary? Any opportunities for improvement you noticed?

@pepopowitz I used a similar docusaurus plugin (maybe the same?) for one of my side project, so I already had same background knowledge what files to touch.

As a general improvement from my point of view:

• Our OpenAPI lib creates a json file. haven't tried the plugin with a json as input. If it's not supported it would be nice to have a built-in way within the docs repo to use also json, for example with a json-to-yaml converter (also available as npm module)
• What would be super cool: auto-fetching of OpenAPI spec instead of manually copying it. Our OpenAPI specs are (semi-) publicly available (via github or public url). The script could automatically fetch the latest content and update the docs.

[pepopowitz]

❤️ ❤️ ❤️ ❤️