Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 34 additions & 13 deletions api-playground/openapi/advanced-features.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

## `oneOf`, `anyOf`, `allOf`

For complex datatypes, OpenAPI provides the `oneOf`, `anyOf`, and `allOf` keywords, allowing you to combine schemas in certain ways. You can read more about these keywords in the [Swagger documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), but essentially:

Check warning on line 10 in api-playground/openapi/advanced-features.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

api-playground/openapi/advanced-features.mdx#L10

Did you really mean 'datatypes'?

- `oneOf` functions like an "exclusive-or" operator
- `anyOf` functions like an "or" operator
Expand Down Expand Up @@ -54,7 +54,7 @@

### Providing options with `oneOf` and `anyOf`

When you use `oneOf` or `anyOf`, Mintlify displays the options in a tabbed container. To give your options helpful names, make sure to give each subschema a `title` field. For example, here's how you might display two different types of delivery addresses:

Check warning on line 57 in api-playground/openapi/advanced-features.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

api-playground/openapi/advanced-features.mdx#L57

Did you really mean 'subschema'?

```yaml
delivery_address:
Expand Down Expand Up @@ -136,40 +136,61 @@
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!)"
}
}
}
Expand Down