diff --git a/api-playground/asyncapi/setup.mdx b/api-playground/asyncapi/setup.mdx index 4700d56ab..aba5408b5 100644 --- a/api-playground/asyncapi/setup.mdx +++ b/api-playground/asyncapi/setup.mdx @@ -71,7 +71,7 @@ You can add an `asyncapi` field to any tab or group in the navigation of your `d the **api-reference** folder of the docs repo. -## Channel Page +## Channel page If you want more control over how you order your channels or if you want to just reference a single channel, you can create an MDX file with the `asyncapi` field in the frontmatter. diff --git a/api-playground/customization/adding-sdk-examples.mdx b/api-playground/customization/adding-sdk-examples.mdx new file mode 100644 index 000000000..9d63857f3 --- /dev/null +++ b/api-playground/customization/adding-sdk-examples.mdx @@ -0,0 +1,49 @@ +--- +title: "Adding SDK examples" +description: "Display language-specific code samples alongside your API endpoints to show developers how to use your SDKs" +--- + +If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages. + +This property can be added to any request method and has the following schema. + + + The language of the code sample. + + + + The label for the sample. This is useful when providing multiple examples for a single endpoint. + + + + The source code of the sample. + + +Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. + +```yaml +paths: + /plants: + get: + ... + x-codeSamples: + - lang: bash + label: List all unwatered plants + source: | + planter list -u + - lang: javascript + label: List all unwatered plants + source: | + const planter = require('planter'); + planter.list({ unwatered: true }); + - lang: bash + label: List all potted plants + source: | + planter list -p + - lang: javascript + label: List all potted plants + source: | + const planter = require('planter'); + planter.list({ potted: true }); +``` + diff --git a/api-playground/customization/complex-data-types.mdx b/api-playground/customization/complex-data-types.mdx new file mode 100644 index 000000000..c49d3159d --- /dev/null +++ b/api-playground/customization/complex-data-types.mdx @@ -0,0 +1,95 @@ +--- +title: "Complex data types" +description: "Describe APIs with flexible schemas, optional properties, and multiple data formats using `oneOf`, `anyOf`, and `allOf` keywords" +--- + +When your API accepts multiple data formats, has conditional fields, or uses inheritance patterns, OpenAPI's schema composition keywords help you document these flexible structures. Using `oneOf`, `anyOf`, and `allOf`, you can describe APIs that handle different input types or combine multiple schemas into comprehensive data models. + +## `oneOf`, `anyOf`, `allOf` keywords + +For complex data types, OpenAPI provides keywords for combining schemas: + +- `allOf`: Combines multiple schemas (like merging objects or extending a base schema). Functions like an `and` operator. +- `anyOf`: Accepts data matching any of the provided schemas. Functions like an `or` operator. +- `oneOf`: Accepts data matching exactly one of the provided schemas. Functions like an `exclusive-or` operator. + +Mintlify treats `oneOf` and `anyOf` identically since the practical difference rarely affects using the API. + +For detailed specifications of these keywords see the [OpenAPI documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/). + +The `not` keyword is currently unsupported. + +### Combining schemas with `allOf` + +When you use `allOf`, Mintlify performs some preprocessing on your OpenAPI document to display complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging OpenAPI's reusable [components](https://swagger.io/docs/specification/components/). + +```yaml +org_with_users: + allOf: + - $ref: '#/components/schemas/Org' + - type: object + properties: + users: + type: array + description: An array containing all users in the organization +... +components: + schemas: + Org: + type: object + properties: + id: + type: string + description: The ID of the organization +``` + + + + + The ID of the organization + + + An array containing all users in the organization + + + + +### Providing options with `oneOf` and `anyOf` + +When you use `oneOf` or `anyOf`, the options are displayed in a tabbed container. Specify a `title` field in each subschema to give your options names. For example, here's how you might display two different types of delivery addresses: + +```yaml +delivery_address: + oneOf: + - title: StreetAddress + type: object + properties: + address_line_1: + type: string + description: The street address of the recipient + ... + - title: POBox + type: object + properties: + box_number: + type: string + description: The number of the PO Box + ... +``` + + +
+ + + + The street address of the residence + + + + + The number of the PO Box + + + +
+ diff --git a/api-playground/customization/managing-page-visibility.mdx b/api-playground/customization/managing-page-visibility.mdx new file mode 100644 index 000000000..08a9b7d01 --- /dev/null +++ b/api-playground/customization/managing-page-visibility.mdx @@ -0,0 +1,85 @@ +--- +title: "Managing page visibility" +description: "Control which endpoints from your OpenAPI specification appear in your documentation navigation" +--- + +You can control which OpenAPI operations get published as documentation pages and their visibility in navigation. This is useful for internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation. + +If your pages are autogenerated from an OpenAPI document, you can manage page visibility with the `x-hidden` and `x-excluded` extensions. + +## `x-hidden` + +The `x-hidden` extension creates a page for an endpoint, but hides it from navigation. The page is only accessible by navigating directly to its URL. + +Common use cases for `x-hidden` are: + +- Endpoints you want to document, but not promote. +- Pages that you will link to from other content. +- Endpoints for specific users. + +## `x-excluded` + + +The `x-excluded` extension completely excludes an endpoint from your documentation. + +Common use cases for `x-excluded` are: + +- Internal-only endpoints. +- Deprecated endpoints that you don't want to document. +- Beta features that are not ready for public documentation. + +## Implementation + +Add the `x-hidden` or `x-excluded` extension under the HTTP method in your OpenAPI specification. + +Here are examples of how to use each property in an OpenAPI schema document for an endpoint and a webhook path. + +```json {11, 19} +"paths": { + "/plants": { + "get": { + "description": "Returns all plants from the store", + "parameters": { ... }, + "responses": { ... } + } + }, + "/hidden_plants": { + "get": { + "x-hidden": true, + "description": "Returns all somewhat secret plants from the store", + "parameters": { ... }, + "responses": { ... } + } + }, + "/secret_plants": { + "get": { + "x-excluded": true, + "description": "Returns all top secret plants from the store (do not publish this endpoint!)", + "parameters": { ... }, + "responses": { ... } + } + } +}, +``` + +```json {9, 15} +"webhooks": { + "/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": { + "x-excluded": true, + "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)" + } + } +} +``` diff --git a/api-playground/customization/multiple-responses.mdx b/api-playground/customization/multiple-responses.mdx new file mode 100644 index 000000000..c49337854 --- /dev/null +++ b/api-playground/customization/multiple-responses.mdx @@ -0,0 +1,31 @@ +--- +title: "Multiple responses" +description: "Show response variations for the same endpoint" +--- + +If your API returns different responses based on input parameters, user context, or other conditions of the request, you can document multiple response examples with the `examples` property. + +This property can be added to any response and has the following schema. + +```yaml +responses: + "200": + description: Successful response + content: + application/json: + schema: + $ref: "#/components/schemas/YourResponseSchema" + examples: + us: + summary: Response for United States + value: + countryCode: "US" + currencyCode: "USD" + taxRate: 0.0825 + gb: + summary: Response for United Kingdom + value: + countryCode: "GB" + currencyCode: "GBP" + taxRate: 0.20 +``` \ No newline at end of file diff --git a/api-playground/mdx/authentication.mdx b/api-playground/mdx/authentication.mdx index feb71f131..a1bf0cc73 100644 --- a/api-playground/mdx/authentication.mdx +++ b/api-playground/mdx/authentication.mdx @@ -3,13 +3,13 @@ title: "Authentication" description: "You can set authentication parameters to let users use their real API keys." --- -## Enabling Authentication +## Enabling authentication -You can add an authentication method to your docs.json to enable it on every page or you can set it on a per-page basis. +You can add an authentication method to your `docs.json` to enable it globally on every page or you can set it on a per-page basis. -The page's authentication method will override docs.json if both are set. +A page's authentication method will override a global method if both are set. -### Bearer Token +### Bearer token @@ -32,7 +32,7 @@ authMethod: "bearer" -### Basic Authentication +### Basic authentication @@ -55,7 +55,7 @@ authMethod: "basic" -### API Key +### API key diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx index d0036296f..b6beb7ebc 100644 --- a/api-playground/mdx/configuration.mdx +++ b/api-playground/mdx/configuration.mdx @@ -1,9 +1,11 @@ --- title: 'MDX Setup' -description: 'Generate docs pages for your API endpoints using MDX' +description: 'Generate docs pages for your API endpoints using `MDX`' --- -Mintlify allows you to define your API endpoints using a combination of `docs.json` configuration, MDX metadata fields, and the `` component. From the defined endpoints, we generate an API playground, request examples, and response examples. +You can manually define API endpoints in individual `MDX` files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most API documentation projects as it's more maintainable and feature-rich. However, MDX can be useful for documenting small APIs, prototyping, or when you want to feature API endpoints alongside other content. + +To generate pages for API endpoints using `MDX`, configure your API settings in `docs.json`, create individual `MDX` files for each endpoint, and use components like `` to define parameters. From these definitions, Mintlify generates interactive API playgrounds, request examples, and response examples. @@ -21,7 +23,7 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js } ``` - If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field: + If you want to hide the API playground, use the `display` field. You do not need to include an auth method if you hide the playground. ```json "api": { @@ -31,12 +33,12 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js } ``` - Find a full list of API configurations [here](settings#param-api). + Find a full list of API configurations in [Settings](/settings#api-configurations). - Each API endpoint page should have a corresponding MDX file. At the top of each file, define: + Each API endpoint page should have a corresponding `MDX` file. At the top of each file, define `title` and `api`: ```md --- @@ -53,11 +55,11 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js - If you have `server` configured in [docs.json](settings), you can use relative paths like `/v1/endpoint`. + If you have a `server` field configured in `docs.json`, you can use relative paths like `/v1/endpoint`. - You can also override the globally-defined display mode for the API playground per page by adding `playground` at the top of the MDX file: + You can override the globally-defined display mode for the API playground per page by adding `playground` at the top of the `MDX` file: ```md --- @@ -69,6 +71,95 @@ Mintlify allows you to define your API endpoints using a combination of `docs.js - Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs [here](navigation). + Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `docs.json`. Learn more about structuring your docs in [Navigation](/navigation). + +## Enabling authentication + +You can add an authentication method to your `docs.json` to enable it globally on every page or you can set it on a per-page basis. + +A page's authentication method will override a global method if both are set. + +### Bearer token + + + +```json docs.json +"api": { + "mdx": { + "auth": { + "method": "bearer" + } + } +} +``` + +```md Page Metadata +--- +title: "Your page title" +authMethod: "bearer" +--- +``` + + + +### Basic authentication + + + +```json docs.json +"api": { + "mdx": { + "auth": { + "method": "basic" + } + } +} +``` + +```md Page Metadata +--- +title: "Your page title" +authMethod: "basic" +--- +``` + + + +### API key + + + +```json docs.json +"api": { + "mdx": { + "auth": { + "method": "key", + "name": "x-api-key" + } + } +} +``` + +```md Page Metadata +--- +title: "Your page title" +authMethod: "key" +--- +``` + + + +### None + +The `none` authentication method is useful to disable authentication on a specific endpoint after setting a default in docs.json. + + +```md Page Metadata +--- +title: "Your page title" +authMethod: "none" +--- +``` + diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx new file mode 100644 index 000000000..58bb43485 --- /dev/null +++ b/api-playground/openapi-setup.mdx @@ -0,0 +1,241 @@ +--- +title: "OpenAPI Setup" +description: "Reference OpenAPI endpoints in your docs pages" +icon: "file-json" +--- + +OpenAPI is a specification for describing REST APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive API documentation and keep it up to date. + +## Add an OpenAPI specification file + +To document your endpoints with OpenAPI, you need a valid OpenAPI document in either JSON or YAML format that follows the [OpenAPI specification 3.0\+](https://swagger.io/specification/). + +### Describing your API + +We recommend the following resources to learn about and construct your OpenAPI documents. + +- [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. +- [Swagger Editor](https://editor.swagger.io/) to edit, validate, and debug your OpenAPI document. +- [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. + + +### Specifying the URL for your API + +To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API's base URL. + +```json +{ + "servers": [ + { + "url": "https://api.example.com/v1" + } + ] +} +``` + +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. + +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. + +### Specifying authentication + +To enable authentication in your API documentation and playground, configure the `securitySchemes` and `security` fields in your OpenAPI document. The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. + + + + Add a `securitySchemes` field to define how users authenticate. + + This example shows a configuration for bearer authentication. + + ```json + { + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + } + } + } + } + ``` + + + + Add a `security` field to require authentication. + + ```json + { + "security": [ + { + "bearerAuth": [] + } + ] + } + ``` + + + + +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. +- [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. + +## Auto-populate API pages + +You can add an `openapi` field to any navigation element in your `docs.json` to auto-populate your docs with a page for each specified endpoint. The `openapi` field can contain the path to an OpenAPI document in your docs repo or the URL of a hosted OpenAPI document. + +The metadata for the generated pages will have the following default values: + +- `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. +- `description`: The `description` field from the OpenAPI operation, if present. +- `version`: The `version` value from the anchor or tab, if present. +- `deprecated`: The `deprecated` field from the OpenAPI operation, if present. If `true`, a deprecated label will appear next to the endpoint title in the side navigation and on the endpoint page. + + + If you have some endpoints in your OpenAPI schema that you want to exclude from your auto-populated API pages, add the [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) property to the endpoint. + + +### Example with navigation tabs + +```json {5} +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" + } + ] +} +``` + +### Example with navigation groups + +```json {8-11} +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "groups": [ + { + "group": "Endpoints", + "openapi": { + "source": "/path/to/openapi-1.json", + "directory": "api-reference" + } + } + ] + } + ] +} +``` + + + The directory field is optional. If not specified, the files will be placed in the `api-reference` directory of the docs repo. + + +## Create `MDX` files for API pages + +If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you can create `MDX` pages for each operation. See an [example MDX OpenAPI page from MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) and how it appears in their [live documentation](https://docs.mindsdb.com/rest/databases/create-databases). + +### Manually specify files + +Create an `MDX` page for each endpoint and specify which OpenAPI operation to display using the `openapi` field in the frontmatter. + +When you reference an OpenAPI operation this way, the name, description, parameters, responses, and API playground are automatically generated from your OpenAPI document. + +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. + +If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`. + + + +```md Example +--- +title: "Get users" +description: "Returns all plants from the system that the user has access to" +openapi: "/path/to/openapi-1.json GET /users" +deprecated: true +version: "1.0" +--- +``` + +```md Format +--- +title: "title of the page" +description: "description of the page" +openapi: openapi-file-path method path +deprecated: boolean (not required) +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. + + For webhooks, use `webhook` (case insensitive) instead of the HTTP method (like `GET` or `POST`) in your reference. + + +### Autogenerate `MDX` files + +Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents. + + + Your OpenAPI document must be valid or the files will not autogenerate. + + +The scraper generates: + +- An `MDX` page for each operation in the `paths` field of your OpenAPI document. +- If your OpenAPI document is version 3.1\+, an `MDX` page for each operation in the `webhooks` field of your OpenAPI document. +- An array of navigation entries that you can add to your `docs.json`. + + + + ```bash + npx @mintlify/scraping@latest openapi-file + ``` + + + ```bash + npx @mintlify/scraping@latest openapi-file -o api-reference + ``` + + 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. + + + +### Create `MDX` files for OpenAPI schemas + +You can create individual pages for any OpenAPI schema defined in an OpenAPI document's `components.schema` field: + + + +```md Example +--- +openapi-schema: OrderItem +--- +``` + + +```md Format +--- +openapi-schema: "schema-key" +--- +``` + + diff --git a/api-playground/openapi/advanced-features.mdx b/api-playground/openapi/advanced-features.mdx deleted file mode 100644 index 4518a5f54..000000000 --- a/api-playground/openapi/advanced-features.mdx +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: "Advanced Features" -description: "Support for advanced OpenAPI features" ---- - -OpenAPI 3 has some advanced features for describing complex APIs. Here's how you can use them with Mintlify. - -## `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: - -- `oneOf` functions like an "exclusive-or" operator -- `anyOf` functions like an "or" operator -- `allOf` functions like an "and" operator - -The `oneOf` and `anyOf` keywords are treated the same. We have found that, when people use `oneOf`, they often *mean* `anyOf` - and there is often no meaningful difference to the user. - -The `not` keyword is not currently supported. - -### Combining schemas with `allOf` - -Mintlify performs some preprocessing on your OpenAPI document to display these complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging [OpenAPI's reusable `components`](https://swagger.io/docs/specification/components/). - -```yaml -org_with_users: - allOf: - - $ref: '#/components/schemas/Org' - - type: object - properties: - users: - type: array - description: An array containing all users in the organization -... -components: - schemas: - Org: - type: object - properties: - id: - type: string - description: The ID of the organization -``` - - - - - The ID of the organization - - - An array containing all users in the organization - - - - -### 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: - -```yaml -delivery_address: - oneOf: - - title: StreetAddress - type: object - properties: - address_line_1: - type: string - description: The street address of the recipient - ... - - title: POBox - type: object - properties: - box_number: - type: string - description: The number of the PO Box - ... -``` - - -
- - - - The street address of the residence - - - - - The number of the PO Box - - - -
- - -## `x-codeSamples` - -If your users interact with your API using an SDK rather than directly through a network request, you can add code samples to your OpenAPI document, and Mintlify will display them in your OpenAPI pages. You can define your code samples using the `x-codeSamples` extension. This property can be added within any request method, and has the following schema: - - - The language of the code sample. - - - - The label for the sample. This is useful when providing multiple examples for a single endpoint. - - - - The source code of the sample. - - -Here's an example of some code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. - -```yaml -paths: - /plants: - get: - ... - x-codeSamples: - - lang: bash - label: List all unwatered plants - source: | - planter list -u - - lang: javascript - label: List all unwatered plants - source: | - const planter = require('planter'); - planter.list({ unwatered: true }); - - lang: bash - label: List all potted plants - source: | - planter list -p - - lang: javascript - label: List all potted plants - source: | - const planter = require('planter'); - planter.list({ potted: true }); -``` - -## `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 exclude them from having pages generated by adding the property `x-excluded`. - -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 {11, 19} -"paths": { - "/plants": { - "get": { - "description": "Returns all plants from the store", - "parameters": { ... }, - "responses": { ... } - } - }, - "/hidden_plants": { - "get": { - "x-hidden": true, - "description": "Returns all somewhat secret plants from the store", - "parameters": { ... }, - "responses": { ... } - } - }, - "/secret_plants": { - "get": { - "x-excluded": true, - "description": "Returns all top secret plants from the store (do not publish this endpoint!)", - "parameters": { ... }, - "responses": { ... } - } - } -}, -``` - -```json {9, 15} -"webhooks": { - "/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": { - "x-excluded": true, - "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)" - } - } -} -``` - diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx deleted file mode 100644 index 8c70083e8..000000000 --- a/api-playground/openapi/setup.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: "OpenAPI Setup" -description: "Reference OpenAPI endpoints in your docs pages" ---- - -## Add an OpenAPI specification file - -To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI -document in either JSON or YAML format that follows the -[OpenAPI specification](https://swagger.io/specification/). Your document must -follow OpenAPI specification 3.0\+. - - To validate your OpenAPI spec, use our [CLI](https://www.npmjs.com/package/mint) and run this command: \ - `mint openapi-check ` - - - -## Auto-populate API pages - -The fastest way to get started with OpenAPI is to add an `openapi` field to a tab in the `docs.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab. - -**Example with Tabs:** - -```json {5} -"navigation": { - "tabs": [ - { - "tab": "API Reference", - "openapi": "https://petstore3.swagger.io/api/v3/openapi.json" - } - ] -} -``` - - - The above example is with tabs but you can add an `openapi` property to any [navigation division](/navigation) - - -**Example with Groups:** - -```json {8-11} -"navigation": { - "tabs": [ - { - "tab": "API Reference", - "groups": [ - { - "group": "Endpoints", - "openapi": { - "source": "/path/to/openapi-1.json", - "directory": "api-reference" - } - } - ] - } - ] -} -``` - - - The directory field is optional. If not specified, the files will be placed in the **api-reference** folder of the docs repo. - - -When using this option, the metadata for the generated pages will have the following default values: - -- `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. -- `description`: The `description` field from the OpenAPI operation, if present. -- `version`: The `version` value from the anchor or tab, if present. -- `deprecated`: The `deprecated` field from the OpenAPI operation, if present. If true, a deprecated label will appear next to the endpoint in the side navigation and next to the title of the endpoint page. - -There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page. - - - If you have some endpoints in your OpenAPI schema that you don't want pages generated for automatically, you can add the [x-hidden](/api-playground/openapi/advanced-features#x-hidden) property - - -## Create MDX files for API pages - -If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx) from [MindsDB](https://docs.mindsdb.com/rest/databases/create-databases). - -![](/images/mindsdb.png) - -### Manually specify files - -You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field. - - - -By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated from the OpenAPI document. - -If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have -only one OpenAPI file - it will automatically detect your OpenAPI file. - -If you want to reference an external OpenAPI file using this method, provide the file’s URL in the docs.json. See [here](https://mintlify.com/docssettings#param-source-4) for the correct format. - - - -```md Example ---- -title: "Get users" -description: "Returns all plants from the system that the user has access to" -openapi: "/path/to/openapi-1.json GET /users" -deprecated: true -version: "1.0" ---- -``` - - -```md Format ---- -title: "title of the page" -description: "description of the page" -openapi: openapi-file-path method path -deprecated: boolean (not required) -version: "version-string" (not required) ---- -``` - - - - - In most cases, the method and path must match the method and path specified - in the OpenAPI document exactly. If the endpoint doesn't exist in the OpenAPI - file, the page will be empty. - - For webhooks, replace the method (i.e. "POST") with "webhook" (case insensitive) - and the correct method will be generated. - - -### Autogenerate files - -For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper. - -Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) -autogenerates MDX files for your OpenAPI endpoints. - -Each generated page will correspond to an OpenAPI operation under the "paths" section of the OpenAPI schema. -If your OpenAPI document is version 3.1\+, the scraper will also generate pages for webhooks under the "webhooks" section of the OpenAPI schema. - -```bash -npx @mintlify/scraping@latest openapi-file -``` - -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. - -```bash -npx @mintlify/scraping@latest openapi-file -o api-reference -``` - -Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). - -The scraper will output an array of -[Navigation entries](settings#structure) containing your OpenAPI MDX -files. You can either append these entries to your existing Navigation, or -reorder and add the files to your navigation manually. - - - If your OpenAPI document is invalid, the files will not autogenerate. - - -## Create MDX files for OpenAPI schemas - -Mintlify also allows you to create individual pages for any OpenAPI schema -defined in an OpenAPI document's `components.schemas` field: - - - -```md Example ---- -openapi-schema: OrderItem ---- -``` - - -```md Format ---- -openapi-schema: "schema-key" ---- -``` - - diff --git a/api-playground/openapi/writing-openapi.mdx b/api-playground/openapi/writing-openapi.mdx deleted file mode 100644 index a9658fa13..000000000 --- a/api-playground/openapi/writing-openapi.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Writing OpenAPI" -description: "Use OpenAPI features to enhance your documentation" ---- - -## Describing your API - -There are many great tools online for learning about and constructing OpenAPI documents. Here are our favorites: -- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) for familiarizing yourself with the OpenAPI syntax -- [OpenAPI v3.1.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) for all the details about the newest OpenAPI specification -- [Swagger & OpenAPI Validator](https://editor.swagger.io/) for debugging your OpenAPI document -- [Swagger's Editor](https://editor.swagger.io/) for seeing examples in action - - - 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, check out [OpenAPI's blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). - - -## Specifying the URL for your API - -In an OpenAPI document, different API endpoints are specified by their paths, like `/users/{id}`, or maybe simply `/`. To specify the base URL to which these paths should be appended, OpenAPI provides the `servers` field. This field is necessary to use some Mintlify features like the API Playground. Read how to configure the `servers` field in the [Swagger documentation](https://swagger.io/docs/specification/api-host-and-base-path/). - -The API Playground will use these server URLs to determine where to send requests. If multiple servers are specified, a dropdown will appear to allow toggling between servers. If no server is supplied, the API Playground will use simple mode, as there is no way to send a request. - -If different endpoints within your API exist at different URLs, you can [override the server field](https://swagger.io/docs/specification/api-host-and-base-path/#:~:text=%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%C2%A0%20%2D%20southeastasia-,Overriding%20Servers,-The%20global%20servers) for a given path or operation. - -## Specifying authentication - -Nearly all APIs require some method of authentication. OpenAPI provides the `securitySchemes` field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/), [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/), and [API Keys](https://swagger.io/docs/specification/authentication/api-keys/). To apply these authentication methods to your endpoints, OpenAPI uses the `security` field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out [Swagger's documentation and examples](https://swagger.io/docs/specification/authentication/) on the topic. - -The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document. - -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. diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx index 7c4d2a896..f0ea81983 100644 --- a/api-playground/overview.mdx +++ b/api-playground/overview.mdx @@ -1,11 +1,120 @@ --- -title: 'Playground' -description: 'Enable users to interact with your API' -openapi: 'POST /project/update/{projectId}' -hideApiMarker: true -icon: 'play' +title: "Playground" +description: "Enable users to interact with your API" +icon: "play" --- -The API playground is an interactive environment to make requests and preview an API endpoint. +## Overview -This page is automatically generated from the OpenAPI specification. \ No newline at end of file +The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation. + + + API playground for the trigger an update endpoint. + API playground for the trigger an update endpoint. + + +The playground is automatically generated from your OpenAPI specification or AsyncAPI schema so any updates to your API are automatically reflected in the playground. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`. + +We recommend generating your API playground from an OpenAPI specification. See [OpenAPI Setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document. + +## Getting started + + + + + Make sure that your OpenAPI specification file is valid using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint). + + + ``` {2} + /your-project + |- docs.json + |- openapi.json + ``` + + + + Update your `docs.json` to reference your OpenAPI specification. You can add an `openapi` property to any navigation element to auto-populate your docs with a page for each endpoint specified in your OpenAPI document. + + In this example, Mintlify will generate a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation. + + ```json + { + "navigation": [ + { + "group": "API reference", + "openapi": "openapi.json" + } + ] + } + ``` + + + + +## Customizing your playground + +You can customize your API playground by defining the following properties in your `docs.json`. + + + Configurations for the API playground. + + + The display mode of the API playground. + - `"interactive"`: Display the interactive playground. + - `"simple"`: Display a copyable endpoint with no playground. + - `"none"`: Display nothing. + + Defaults to `interactive`. + + + Whether to pass API requests through a proxy server. Defaults to `true`. + + + + + + Configurations for the autogenerated API examples. + + + Example languages for the autogenerated API snippets. + + Languages display in the order specified. + + + Whether to show optional parameters in API examples. Defaults to `all`. + + + + +### Example configuration + +```json +{ + "api": { + "playground": { + "display": "interactive" + }, + "examples": { + "languages": ["curl", "python", "javascript"], + "defaults": "required" + } + } +} +``` + +This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets. + +### Custom `MDX` pages + +When you need more control over your API documentation, create individual `MDX` pages for your endpoints. This allows you to: + +- Customize page metadata +- Add additional content like examples +- Hide specific operations +- Reorder pages in your navigation + +See [MDX Setup](/api-playground/mdx/configuration) for more information on creating individual pages for your API endpoints. + +## Further reading + +- [AsyncAPI Setup](/api-playground/asyncapi/setup) for more information on creating your AsyncAPI schema to generate WebSocket reference pages. diff --git a/docs.json b/docs.json index 3b85c5ca2..6b562509d 100644 --- a/docs.json +++ b/docs.json @@ -68,13 +68,15 @@ "group": "API Pages", "pages": [ "api-playground/overview", + "api-playground/openapi-setup", { - "group": "OpenAPI", - "icon": "file-json", + "group": "Customization", + "icon": "wrench", "pages": [ - "api-playground/openapi/setup", - "api-playground/openapi/writing-openapi", - "api-playground/openapi/advanced-features" + "api-playground/customization/complex-data-types", + "api-playground/customization/adding-sdk-examples", + "api-playground/customization/managing-page-visibility", + "api-playground/customization/multiple-responses" ] }, { @@ -89,8 +91,8 @@ "group": "MDX", "icon": "markdown", "pages": [ - "api-playground/mdx/configuration", - "api-playground/mdx/authentication" + "api-playground/mdx/configuration", + "api-playground/mdx/authentication" ] }, "api-playground/troubleshooting" @@ -375,5 +377,19 @@ "chatgpt", "claude" ] - } + }, + "redirects": [ + { + "source": "/api-playground/openapi/advanced-features", + "destination": "/api-playground/customization" + }, + { + "source": "/api-playground/openapi/setup", + "destination": "/api-playground/openapi-setup" + }, + { + "source": "/api-playground/openapi/writing-openapi", + "destination": "/api-playground/openapi-setup" + } + ] } \ No newline at end of file diff --git a/images/mindsdb.png b/images/mindsdb.png deleted file mode 100644 index 21de05d15..000000000 Binary files a/images/mindsdb.png and /dev/null differ diff --git a/images/playground/API-playground-dark.png b/images/playground/API-playground-dark.png new file mode 100644 index 000000000..c09c0f950 Binary files /dev/null and b/images/playground/API-playground-dark.png differ diff --git a/images/playground/API-playground-light.png b/images/playground/API-playground-light.png new file mode 100644 index 000000000..646f7c540 Binary files /dev/null and b/images/playground/API-playground-light.png differ diff --git a/integrations/sdks/stainless.mdx b/integrations/sdks/stainless.mdx index b8a6308f5..f82e72b52 100644 --- a/integrations/sdks/stainless.mdx +++ b/integrations/sdks/stainless.mdx @@ -26,6 +26,6 @@ description: Automate SDK example snippets in your API playground /> - In your `docs.json` file, add the URL from Stainless to the `openapi` field. See [OpenAPI Setup](/api-playground/openapi/setup) for more information. + In your `docs.json` file, add the URL from Stainless to the `openapi` field. See [OpenAPI Setup](/api-playground/openapi-setup) for more information.