Update to Redocly

{
  "description": "Use when adding or changing API reference docs in a Redocly project: rendering an OpenAPI, AsyncAPI, GraphQL, or SOAP (WSDL) description, its URL and place in the sidebar or navbar, code samples, the Try it (Replay) console, the mock server, x- extensions such as x-tagGroups or x-codeSamples, or embedding one operation or schema in a Markdown page. Not for linting, bundling, or splitting API descriptions (use redocly-cli).",
  "included_files": [],
  "name": "redocly-api-docs",
  "skill_md_contents": "---\nname: redocly-api-docs\ndescription: >-\n  Use when adding or changing API reference docs in a Redocly project: rendering an OpenAPI, AsyncAPI,\n  GraphQL, or SOAP (WSDL) description, its URL and place in the sidebar or navbar, code samples, the\n  Try it (Replay) console, the mock server, x- extensions such as x-tagGroups or x-codeSamples, or\n  embedding one operation or schema in a Markdown page.\n  Not for linting, bundling, or splitting API descriptions (use redocly-cli).\n---\n\n# Add API reference docs to a Redocly project\n\n## The file is the reference\n\nPut the API description anywhere in the project.\nRealm renders it as reference docs at the path of the file, with a sidebar built from its tags and operations.\nOpenAPI, AsyncAPI, and GraphQL files need no configuration, and WSDL needs the SOAP plugin first, see below.\n\n| File | URL |\n| --- | --- |\n| `apis/cafe-api.yaml` | `/apis/cafe-api` |\n| `api-reference/index.yaml` | `/api-reference` |\n\nSupported descriptions: OpenAPI (any version, YAML or JSON), AsyncAPI 3.0, GraphQL SDL (`.graphql`, `.gql`), and WSDL with the SOAP plugin.\nFor a new description, use the latest OpenAPI or AsyncAPI version unless the user asks for another.\n\nTo change the URL, move or rename the file, and the mock server path below follows it.\nLink to the reference by its file path, like any page:\n\n```yaml\n# sidebars.yaml, navbar, or footer\n- page: apis/cafe-api.yaml\n  label: Cafe API\n```\n\nThe internal sidebar of the reference comes from the description itself.\nShape it with `x-tagGroups` and the other extensions below, not with `sidebars.yaml`.\nRender the description as it is.\nHiding operations, with `x-internal` and a decorator or by leaving a tag out of `x-tagGroups`, and reformatting the file are the user's decisions, so ask first.\n\nFull reference: https://redocly.com/docs/realm/content/api-docs/add-openapi-docs.md\n\n## AsyncAPI, GraphQL, and SOAP\n\n- AsyncAPI 3.0 files render like OpenAPI files, with `asyncapi` options and their own extensions: https://redocly.com/docs/realm/content/api-docs/add-asyncapi-docs.md\n- GraphQL SDL files get a sidebar from their queries, mutations, and types, and `graphql.menu` groups them: https://redocly.com/docs/realm/content/api-docs/add-graphql-docs.md\n- SOAP needs `@redocly/portal-plugin-soap-api` and `@redocly/realm` in `package.json`, `plugins: ['@redocly/portal-plugin-soap-api/plugin.js']` in `redocly.yaml`, and `.wsdl` files: https://redocly.com/docs/realm/content/api-docs/add-soap-docs.md\n\n## OpenAPI display options\n\nOptions go under the top-level `openapi` key of `redocly.yaml` for every API, or under `apis.<name>.openapi` for one API.\nBoth merge, and the per-API value wins.\nWith one API, the top-level key is enough.\nUse the per-API form for a setting that must not apply to APIs added later.\n`asyncapi` and `graphql` work the same way.\n\n```yaml\nopenapi:\n  layout: stacked\n  hideReplay: true\n  codeSamples:\n    languages:\n      - lang: curl\n      - lang: Python\napis:\n  cafe_api:\n    root: apis/cafe-api.yaml\n    openapi:\n      hideReplay: false\n```\n\n| Option | Default | Effect |\n| --- | --- | --- |\n| `layout` | `three-panel` | `stacked` moves the samples into the middle panel |\n| `hideReplay` | `false` | Hide the Try it buttons |\n| `codeSamples.languages` | a default set | Which generated samples to show, in order, by `lang` (`curl`, `JavaScript`, `Python`, ...), and `label` renames a tab. Supported values: https://redocly.com/docs/realm/config/openapi/code-samples.md |\n| `hideDownloadButtons` | `false` | Hide the download links, which does not hide the description |\n| `downloadUrls` | - | Download links: a list of `title` and `url` |\n| `schemaDefinitionsTagName` | - | List all schemas in a sidebar section with this name |\n| `showExtensions` | `false` | Show `x-` fields in the docs |\n| `sortRequiredPropsFirst` | `false` | Required properties first |\n| `excludeFromSearch` | `false` | Keep the API out of search and `llms.txt` |\n\nAll options: https://redocly.com/docs/realm/config/openapi.md\n\nAn `apis` entry is optional.\nAdd one only when an API needs its own lint rules, decorators, or rendering options, or a CLI shortcut name such as `redocly lint cafe_api`.\nIts key is a name, or `name@version`, and `root` is required.\nIt does not add a page and does not set the URL: https://redocly.com/docs/realm/config/apis.md\n\n## Code samples\n\nRealm generates request samples in the configured languages.\nFor a language it does not generate, or a hand-written sample, add `x-codeSamples` to the operation.\n`source` is inline code or a `$ref` to a file:\n\n```yaml\npaths:\n  /orders:\n    post:\n      x-codeSamples:\n        - lang: Python\n          source:\n            $ref: ../code-samples/create-order.py\n```\n\nWhen `codeSamples.languages` is set, list the sample's `lang` there too, or the sample does not show.\n\nFull reference: https://redocly.com/docs/realm/config/openapi/code-samples.md\n\n## Try it and the mock server\n\nReplay is the Try it console.\nHide it for all APIs or one API with `hideReplay`, or for one operation with `x-hideReplay: true`.\nIt sends requests through a built-in CORS proxy, so the API needs no CORS headers.\n\nThe mock server is on by default and answers with the examples from the description at `/_mock/<path-to-description>/`, for example `/_mock/apis/cafe-api/`.\nTurn it off with `mockServer.off: true`: https://redocly.com/docs/realm/config/mock-server.md\n\nPrefilling request values, headers, or auth for Replay is a customization (an ejected `configure.ts`): https://redocly.com/docs/realm/customization/configure-request-values.md\n\n## OpenAPI extensions\n\n| Extension | Where | Effect |\n| --- | --- | --- |\n| `x-tagGroups` | root | Group tags in the sidebar, and a tag in no group does not show |\n| `x-displayName` | tag | Tag label in the sidebar |\n| `x-traitTag` | tag | A tag that describes operations without grouping them |\n| `x-tags` | schema | Add a schema to a tag section |\n| `x-badges` | operation, parameter, schema | Badges with `name`, `color`, `position` |\n| `x-enumDescriptions` | schema | Describe enum values, and only listed values show |\n| `x-rbac` | any object | Team-to-role map that hides the object from other users |\n| `x-seo` | operation | Title, description, and image of the operation page |\n| `x-webhooks` | root | Webhooks in OpenAPI 3.0 and earlier |\n\n```yaml\nx-tagGroups:\n  - name: Ordering\n    tags: [Menu, Orders]\n  - name: Account\n    tags: [Customers]\n```\n\nAll extensions: https://redocly.com/docs/realm/content/api-docs/openapi-extensions.md\n\n## API content in Markdown pages\n\nShow one operation or schema in a guide with the API content tags:\n\n```markdoc\n{% openapi-code-sample descriptionFile=\"../apis/cafe-api.yaml\" operationId=\"createOrder\" language=\"curl\" /%}\n```\n\n`openapi-response-sample` shows the response and `replay-openapi` embeds Try it for one operation.\nBoth take the same `descriptionFile` and `operationId` (or `pointer`) attributes.\n`json-schema` takes a `schema` object: `{% json-schema schema={ \"$ref\": \"../apis/cafe-api.yaml#/components/schemas/Order\" } /%}`.\nLanguage values are case-sensitive, as in `codeSamples`.\n\nReferences: https://redocly.com/docs/realm/content/markdoc-tags/openapi-code-sample.md, https://redocly.com/docs/realm/content/markdoc-tags/replay-openapi.md, https://redocly.com/docs/realm/content/markdoc-tags/json-schema.md\n\n## Verify\n\n1. For OpenAPI and AsyncAPI, `npx @redocly/cli lint apis/cafe-api.yaml` validates the description.\n   Add `--extends recommended` when `redocly.yaml` configures no rules.\n   GraphQL and WSDL files are checked by the preview only.\n   Lint rules, bundling, and the other commands are in the `redocly-cli` skill (https://redocly.com/.well-known/agent-skills/redocly-cli/SKILL.md), and custom rules in `redocly-lint-rules` (https://redocly.com/.well-known/agent-skills/redocly-lint-rules/SKILL.md).\n2. Follow Preview and verify in the `redocly` skill (https://redocly.com/.well-known/agent-skills/redocly/SKILL.md).\n   Run `TERM=dumb npx @redocly/cli preview` in the background, read its output, and open the reference page.\n3. After a change to `redocly.yaml`, run `npx @redocly/cli check-config`.\n\n## Common mistakes\n\n| Mistake | Correct approach |\n| --- | --- |\n| An `apis` entry to publish or move an API | The file path sets the URL |\n| `hideReplay` or other options directly under `apis.<name>` | Under `openapi`, or `apis.<name>.openapi` |\n| `x-tagGroups` that leaves out a tag | List every tag, as tags in no group do not show |\n| `hideDownloadButtons` to protect an API | It hides buttons only, so use `x-rbac` or `access.rbac` |\n| A code sample language that is not generated | Add it with `x-codeSamples` |\n"
}