diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index e47497e1e..29b8cf6e3 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -22,7 +22,11 @@ We recommend the following resources to learn about and construct your OpenAPI d - [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint openapi-check `. - Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, see [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) in the OpenAPI blog. + Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information + is applicable to v3.1. For more information on the differences between v3.0 + and v3.1, see [Migrating from OpenAPI 3.0 to + 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) + in the OpenAPI blog. ### Specifying the URL for your API @@ -53,34 +57,34 @@ To enable authentication in your API documentation and playground, configure the Add a `securitySchemes` field to define how users authenticate. - This example shows a configuration for bearer authentication. +This example shows a configuration for bearer authentication. - ```json - { - "components": { - "securitySchemes": { - "bearerAuth": { +```json +{ + "components": { + "securitySchemes": { + "bearerAuth": { "type": "http", "scheme": "bearer" - } } } } - ``` +} +``` Add a `security` field to require authentication. - ```json - { - "security": [ - { - "bearerAuth": [] - } - ] - } - ``` +```json +{ + "security": [ + { + "bearerAuth": [] + } + ] +} +``` @@ -114,7 +118,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat "metadata": { "title": "List all users", "description": "Fetch paginated user data with filtering options", - "og:title": "Display a list of users", + "og:title": "Display a list of users" } }, "parameters": [ @@ -132,7 +136,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat Add content before the auto-generated API documentation using `x-mint: content`: -```json {6-13} +```json {6-8} { "paths": { "/users": { @@ -223,7 +227,9 @@ Generated endpoint pages have these default metadata values: - `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. - To exclude specific endpoints from your auto-generated API pages, add the [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) property to the operation in your OpenAPI spec. + To exclude specific endpoints from your auto-generated API pages, add the + [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) + property to the operation in your OpenAPI spec. There are two approaches for adding endpoint pages into your documentation: @@ -275,7 +281,9 @@ You can use multiple OpenAPI specifications in different navigation sections: ``` - The `directory` field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the `api-reference` directory of your repo. + The `directory` field is optional and specifies where generated API pages are + stored in your docs repo. If not specified, defaults to the `api-reference` + directory of your repo. ### Selective endpoints @@ -369,7 +377,9 @@ When you reference an OpenAPI operation this way, the name, description, paramet If you have multiple OpenAPI files, include the file path in your reference to ensure Mintlify finds the correct OpenAPI document. If you have only one OpenAPI file, Mintlify will detect it automatically. - This approach works regardless of whether you have set a default OpenAPI spec in your navigation. You can reference any endpoint from any OpenAPI spec by including the file path in the frontmatter. + This approach works regardless of whether you have set a default OpenAPI spec + in your navigation. You can reference any endpoint from any OpenAPI spec by + including the file path in the frontmatter. If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`. @@ -399,7 +409,9 @@ version: "version-string" (not required) - The method and path must exactly match the definition in your OpenAPI specification. If the endpoint doesn't exist in the OpenAPI file, the page will be empty. + The method and path must exactly match the definition in your OpenAPI + specification. If the endpoint doesn't exist in the OpenAPI file, the page + will be empty. ### Autogenerate `MDX` files @@ -428,6 +440,7 @@ The scraper generates: ``` Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory. + @@ -443,7 +456,6 @@ openapi-schema: OrderItem --- ``` - ```mdx Format --- openapi-schema: "schema-key" @@ -475,5 +487,6 @@ openapi: "path/to/openapi-file webhook example-webhook-name" ``` - The webhook name must exactly match the key defined in your OpenAPI specification's `webhooks` field. + The webhook name must exactly match the key defined in your OpenAPI + specification's `webhooks` field.