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
2 changes: 1 addition & 1 deletion api-playground/openapi-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

### Describing your API

We recommend the following resources to learn about and construct your OpenAPI documents.

Check warning on line 16 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L16

Try to avoid using first-person plural like 'We'.

- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax.
- [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification.
Expand Down Expand Up @@ -44,9 +44,9 @@

In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}` or simply `/`. The base URL defines where these paths should be appended. For more information on how to configure the `servers` field, see [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) in the OpenAPI documentation.

The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown will allow users to toggle between servers. If you do not specify a server, the API playground will use simple mode since it cannot send requests without a base URL.

Check warning on line 47 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L47

Avoid using 'will'.

If your API has endpoints that exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) for a given path or operation.

Check warning on line 49 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L49

Try to avoid using first-person plural like 'our'.

### Specifying authentication

Expand Down Expand Up @@ -91,16 +91,16 @@
Common authentication types include:

- [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): For header, query, or cookie-based keys.
- [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): For JWT or OAuth tokens.

Check warning on line 94 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L94

Spell out 'JWT', if it's unfamiliar to the audience.
- [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): For username and password.

If different endpoints within your API require different methods of authentication, you can [override the security field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation.

For more information on defining and applying authentication, see [Authentication](https://swagger.io/docs/specification/authentication/) in the OpenAPI documentation.

## `x-mint` extension

Check warning on line 101 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L101

'extension' should use sentence-style capitalization.

The `x-mint` extension is a custom OpenAPI extension that provides additional control over how your API documentation is generated and displayed.

Check warning on line 103 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L103

In general, use active voice instead of passive voice ('is generated').

### Metadata

Expand Down Expand Up @@ -157,7 +157,7 @@

The `content` extension supports all Mintlify MDX components and formatting.

### Href

Check warning on line 160 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L160

'Href' should use sentence-style capitalization.

Change the URL of the endpoint page in your docs using `x-mint: href`:

Expand All @@ -184,7 +184,7 @@
}
```

When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page.

Check warning on line 187 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L187

Avoid using 'will'.

### MCP

Expand Down Expand Up @@ -260,14 +260,14 @@

Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.

The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.

Check warning on line 263 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L263

Use 'path' instead of 'file path'.

Generated endpoint pages have these default metadata values:

- `title`: The operation's `summary` field, if present. If there is no `summary`, the title is generated from the HTTP method and endpoint.

Check warning on line 267 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L267

In general, use active voice instead of passive voice ('is generated').
- `description`: The operation's `description` field, if present.
- `version`: The `version` value from the parent anchor or tab, if present.
- `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label will appear next to the endpoint title in the side navigation and on the endpoint page.

Check warning on line 270 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L270

Avoid using 'will'.

<Tip>
To exclude specific endpoints from your auto-generated API pages, add the
Expand All @@ -282,7 +282,7 @@

### Dedicated API sections

Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification will be included:

Check warning on line 285 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L285

Avoid using 'will'.

Check warning on line 285 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L285

In general, use active voice instead of passive voice ('be included').

```json {5}
"navigation": {
Expand Down Expand Up @@ -365,7 +365,7 @@

#### OpenAPI spec inheritance

OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent's OpenAPI specification unless they define their own:

Check warning on line 368 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L368

In general, use active voice instead of passive voice ('are inherited').

```json {3, 7-8, 11, 13-14}
{
Expand All @@ -390,7 +390,7 @@

#### Individual endpoints

Reference specific endpoints without setting a default OpenAPI specification by including the file path:

Check warning on line 393 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L393

Use 'path' instead of 'file path'.

```json {5-6}
"navigation": {
Expand Down Expand Up @@ -462,7 +462,7 @@
Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.

<Note>
Your OpenAPI document must be valid or the files will not autogenerate.

Check warning on line 465 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L465

Avoid using 'will'.

Check warning on line 465 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L465

Use 'won't' instead of 'will not'.
</Note>

The scraper generates:
Expand All @@ -489,7 +489,7 @@

### Create `MDX` files for OpenAPI schemas

You can create individual pages for any OpenAPI schema defined in an OpenAPI document's `components.schema` field:
You can create individual pages for any OpenAPI schema defined in an OpenAPI document's `components.schemas` field:

<CodeGroup>

Expand Down Expand Up @@ -527,7 +527,7 @@

## Webhooks

Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.

Check warning on line 530 in api-playground/openapi-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/openapi-setup.mdx#L530

In general, use active voice instead of passive voice ('are supported').

### Define webhooks in your OpenAPI specification

Expand Down