From fb8f62d4bf4d4793b967c85a0d19f1be8779198d Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 14 Nov 2024 11:42:18 -0800 Subject: [PATCH 01/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 88 ++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 39 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 03d9fb9..77b037b 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -10,18 +10,9 @@ document in either JSON or YAML format that follows the [OpenAPI specification](https://swagger.io/specification/). Your document must follow OpenAPI specification 3.0+. -## Autogenerating the API playground - -You can either [autogenerate the API playground](/settings/navigation#tabs) or -create MDX files for the individual OpenAPI endpoints. - ### Auto-populate API pages -You can add an `openapi` field to an object in the `tabs` or `anchors` array in -the `mint.json`. This can either be with OpenAPI documents that are in the docs -repo (json or yaml) or hosted at a link. - -**Example with Anchors:** +The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.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/anchor. ```json {5} { @@ -36,6 +27,27 @@ repo (json or yaml) or hosted at a link. } ``` +When using this option, the metadata for the generated pages will have the follo: + +* Title: the `summary` field from the OpenAPI operation, or + +* Description: The `description` field from the OpenAPI operation + +### + +## Autogenerating the API playground + +You can either [autogenerate the API playground](/settings/navigation#tabs) or +create MDX files for the individual OpenAPI endpoints. + +### Auto-populate API pages + +You can add an `openapi` field to an object in the `tabs` or `anchors` array in +the `mint.json`. This can either be with OpenAPI documents that are in the docs +repo (json or yaml) or hosted at a link. + +**Example with Anchors:** + ![](/images/anchors-autogeneration-anchors.png) **Example with Tabs:** @@ -110,23 +122,23 @@ This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file. - -```md Example ---- -title: "Get users" -openapi: "openapi-1 GET /users" ---- -``` - -```md Format ---- -title: "title of the page" -openapi: openapi-file-name method path ---- -``` - + ```md Example + --- + title: "Get users" + openapi: "openapi-1 GET /users" + --- + ``` + + ```md Format + --- + title: "title of the page" + openapi: openapi-file-name method path + --- + ``` +
+ The method endpoint must match the endpoint specified in the OpenAPI specifications exactly. If the endpoint doesn't exist in the OpenAPI file, @@ -139,17 +151,15 @@ 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" ---- -``` - - + ```md Example + --- + openapi-schema: OrderItem + --- + ``` + + ```md Format + --- + openapi-schema: "schema-key" + --- + ``` + \ No newline at end of file From 8427933479d88b751d8116d5efc51d4b9acb2e4b Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 14 Nov 2024 11:59:51 -0800 Subject: [PATCH 02/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 77b037b..b748c31 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -27,15 +27,17 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` -When using this option, the metadata for the generated pages will have the follo: +When using this option, the metadata for the generated pages will have the following default values: -* Title: the `summary` field from the OpenAPI operation, or +* `title`: The `summary` field from the OpenAPI operation, or a title generated from the HTTP method and endpoint. -* Description: The `description` field from the OpenAPI operation +* `description`: The `description` field from the OpenAPI operation. -### +* `version`: The `version` value from the anchor or tab, if present. -## Autogenerating the API playground +There are some scenarios in which the default behavior isn't sufficient. If you need to customize the page metadata, add additional content, or omit certain OpenAPI operations, you'll need to create MDX pages for each operation. + +## Generating API pages You can either [autogenerate the API playground](/settings/navigation#tabs) or create MDX files for the individual OpenAPI endpoints. From c91f88afbe2e7e746b754784fb328f6f27cf8d14 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:27:58 -0800 Subject: [PATCH 03/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 38 ++++++++++++-------------------- 1 file changed, 14 insertions(+), 24 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 983a6bf..01a2a99 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -29,24 +29,14 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta When using this option, the metadata for the generated pages will have the following default values: -* `title`: The `summary` field from the OpenAPI operation, or a title generated from the HTTP method and endpoint. +* `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. +* `description`: The `description` field from the OpenAPI operation, if present. * `version`: The `version` value from the anchor or tab, if present. There are some scenarios in which the default behavior isn't sufficient. If you need to customize the page metadata, add additional content, or omit certain OpenAPI operations, you'll need to create MDX pages for each operation. -## Generating API pages - -You can either [autogenerate the API playground](/settings/navigation#tabs) or -create MDX files for the individual OpenAPI endpoints. - -### Auto-populate API pages - -You can add an `openapi` field to an object in the `tabs` or `anchors` array in -the `mint.json`. This can either be with OpenAPI documents that are in the docs -repo (json or yaml) or hosted at a link. **Example with Anchors:** @@ -123,19 +113,19 @@ the MDX file to the appropriate OpenAPI file. This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file. -```md Example ---- -title: "Get users" -openapi: "/path/to/openapi-1.json GET /users" ---- -``` + ```md Example + --- + title: "Get users" + openapi: "/path/to/openapi-1.json GET /users" + --- + ``` -```md Format ---- -title: "title of the page" -openapi: openapi-file-path method path ---- -``` + ```md Format + --- + title: "title of the page" + openapi: openapi-file-path method path + --- + ```
From 8aed47591b5d3155a72bfb1f2bd564ecc7e721c4 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:33:17 -0800 Subject: [PATCH 04/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 01a2a99..26de88e 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -14,6 +14,8 @@ follow OpenAPI specification 3.0+. The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.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/anchor. +**Example with Anchors:** + ```json {5} { "anchors": [ @@ -27,19 +29,6 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` -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. - -There are some scenarios in which the default behavior isn't sufficient. If you need to customize the page metadata, add additional content, or omit certain OpenAPI operations, you'll need to create MDX pages for each operation. - - -**Example with Anchors:** - ![](/images/anchors-autogeneration-anchors.png) **Example with Tabs:** @@ -58,13 +47,22 @@ There are some scenarios in which the default behavior isn't sufficient. If you ![](/images/autogeneration-with-tabs.png) +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. + +There are some scenarios in which the default behavior isn't sufficient. If you need to customize the page metadata, add additional content, or omit certain OpenAPI operations, you'll need to create MDX pages for each operation. + + ### Create MDX files for OpenAPI endpoints You can also create MDX files associated with each OpenAPI endpoint if you would like to add additional context to specific pages or have more granular control -over the navigation. Here is -[the code](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) -from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). +over the navigation. Here is [the code](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). ![](/images/elevenlabs-mdx-autogeneration-example.png) From 09c9b572daf1e2f679bba0073a78f3aa0d213e9c Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:47:43 -0800 Subject: [PATCH 05/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 26de88e..4c2155b 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -55,14 +55,12 @@ When using this option, the metadata for the generated pages will have the follo * `version`: The `version` value from the anchor or tab, if present. -There are some scenarios in which the default behavior isn't sufficient. If you need to customize the page metadata, add additional content, or omit certain OpenAPI operations, you'll need to create MDX pages for each operation. +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. ### Create MDX files for OpenAPI endpoints -You can also create MDX files associated with each OpenAPI endpoint if you would -like to add additional context to specific pages or have more granular control -over the navigation. Here is [the code](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). +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/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). This can get ![](/images/elevenlabs-mdx-autogeneration-example.png) From d5e645cfcdbe15ef561c865d1060efc6ba7a6dd9 Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:50:29 -0800 Subject: [PATCH 06/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 4c2155b..6c116ab 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -60,15 +60,15 @@ There are some scenarios in which the default behavior isn't sufficient. If you ### Create MDX files for OpenAPI endpoints -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/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). This can get +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/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). ![](/images/elevenlabs-mdx-autogeneration-example.png) -If you want to autogenerate MDX files for every endpoint in your OpenAPI -document you can use our scraper. #### 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. Use the relative path to the OpenAPI document in your codebase. If you're using a publicly-hosted OpenAPI From f0f7cbc336dfd2b5caa84d1638a35ca6e488cb0b Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:52:07 -0800 Subject: [PATCH 07/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 6c116ab..ddac9b9 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -85,8 +85,7 @@ not specified, the files will populate in the working directory. npx @mintlify/scraping@latest openapi-file -o api-reference ``` -Learn more about our scraping package -[here](https://www.npmjs.com/package/@mintlify/scraping). +Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). The scraper will output an array of [Navigation entries](/settings/global#structure) containing your OpenAPI MDX From 7628e63045b31a5eaef6129dc5356d442f8f951b Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:55:28 -0800 Subject: [PATCH 08/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index ddac9b9..2fb6685 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -101,10 +101,10 @@ reorder and add the files to your navigation manually. By using the OpenAPI reference, the name, description, parameters, responses, -and the API playground will be automatically generated using the specifications. +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 map -the MDX file to the appropriate OpenAPI file. This is not required if you have +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. @@ -126,8 +126,8 @@ only one OpenAPI file - it will automatically detect your OpenAPI file.
- The method endpoint must match the endpoint specified in the OpenAPI - specifications exactly. If the endpoint doesn't exist in the OpenAPI file, + 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. From ad54106bb59761665ab708b69d4a6e445b92919e Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:00:29 -0800 Subject: [PATCH 09/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 2fb6685..bca3574 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -10,7 +10,7 @@ document in either JSON or YAML format that follows the [OpenAPI specification](https://swagger.io/specification/). Your document must follow OpenAPI specification 3.0+. -### Auto-populate API pages +## Auto-populate API pages The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.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/anchor. @@ -58,14 +58,14 @@ When using this option, the metadata for the generated pages will have the follo 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. -### Create MDX files for OpenAPI endpoints +## Create MDX files for OpenAPI endpoints 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/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). ![](/images/elevenlabs-mdx-autogeneration-example.png) -#### Autogenerate files +### 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. @@ -96,7 +96,7 @@ reorder and add the files to your navigation manually. If your OpenAPI document is invalid, the files will not autogenerate. -#### Manually specify files +### Manually specify files From f887f40e802512af149d622cc2f889ef54a4251e Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:02:29 -0800 Subject: [PATCH 10/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index bca3574..ae5b7e2 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -58,7 +58,7 @@ When using this option, the metadata for the generated pages will have the follo 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. -## Create MDX files for OpenAPI endpoints +## 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/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). From c04134e3611a77722e1b078cdad316cbb26230bf Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:05:50 -0800 Subject: [PATCH 11/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index ae5b7e2..759eced 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -103,8 +103,7 @@ reorder and add the files to your navigation manually. 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 +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. From dd66ab23cea18da2e20a235d1e85444cdf6161ea Mon Sep 17 00:00:00 2001 From: Ronan McCarter <63772591+rpmccarter@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:08:48 -0800 Subject: [PATCH 12/12] Documentation edits made through Mintlify web editor --- api-playground/openapi/setup.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 759eced..bbfdfe3 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -98,6 +98,8 @@ reorder and add the files to your navigation manually. ### 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,