diff --git a/api-playground/openapi/advanced-features.mdx b/api-playground/openapi/advanced-features.mdx index cf92428e1..4518a5f54 100644 --- a/api-playground/openapi/advanced-features.mdx +++ b/api-playground/openapi/advanced-features.mdx @@ -136,40 +136,61 @@ paths: planter.list({ potted: true }); ``` -## `x-hidden` +## `x-hidden` and `x-excluded` -If your pages are [autogenerated](/api-playground/openapi/setup) from an OpenAPI document, but there are some paths that you don't want to create pages for, you can hide them by adding the property `x-hidden`. +If your pages are [autogenerated](/api-playground/openapi/setup) from an OpenAPI document, but there are some paths that you don't want to create pages for, you can exclude them from having pages generated by adding the property `x-excluded`. -You can add the `x-hidden` tag under endpoint or webhook paths below the method. +If you want to have pages generated, but not have them appear in the navigation, add `x-hidden`. + +You can add the `x-hidden` or `x-excluded` tag under endpoint or webhook paths below the method. Here's are examples of how that would look in an OpenAPI schema document for an endpoint or a webhook path: -```json {14} +```json {11, 19} "paths": { "/plants": { "get": { "description": "Returns all plants from the store", "parameters": { ... }, - "responses": { ... }, + "responses": { ... } } - } + }, + "/hidden_plants": { + "get": { + "x-hidden": true, + "description": "Returns all somewhat secret plants from the store", + "parameters": { ... }, + "responses": { ... } + } + }, "/secret_plants": { "get": { - "description": "Returns all secret plants from the store (do not publish this endpoint!)", + "x-excluded": true, + "description": "Returns all top secret plants from the store (do not publish this endpoint!)", "parameters": { ... }, - "responses": { ... }, - "x-hidden": true + "responses": { ... } } } }, ``` -```json {5} +```json {9, 15} "webhooks": { - "/secret_pants_hook": { + "/plants_hook": { + "post": { + "description": "Webhook for information about a new plant added to the store", + } + }, + "/hidden_plants_hook": { + "post": { + "x-hidden": true, + "description": "Webhook for somewhat secret information about a new plant added to the store" + } + }, + "/secret_plants_hook": { "post": { - "description": "Secret webhook for information about a new plant added to the store", - "x-hidden": true + "x-excluded": true, + "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)" } } }