Skip to content

Commit 6f00cd2

Browse files
ethanpalmethanpalm
authored
API playground docs refresh (#723)
* add outline * update overview * add a quickstart * update grouping and titles * Add getting started info to overview * update info on adding openAPI doc * remove repeated link * update info on auto-generating pages * remove mindsdb image * update MDX info * remove files combined into OpenAPI setup * add redirects * rewrite MDX intro * upate steps * undo reorging MDX content * create files for customization group * update `docs.json` * add content for complex data types * add content for managing page visibility * Add SDK examples content * delete advanced features page * add description for SDK page * add info on multiple responses * fix broken links * Copilot edits * Copy edit overview * Copy edit of OpenAPI setup * Copyedit customization pages * consistent heading capitalization * add reviewer feedback
1 parent f3479a4 commit 6f00cd2

17 files changed

+748
-444
lines changed

‎api-playground/asyncapi/setup.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ You can add an `asyncapi` field to any tab or group in the navigation of your `d
7171
the **api-reference** folder of the docs repo.
7272
</Note>
7373

74-
## Channel Page
74+
## Channel page
7575

7676
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.
7777

‎api-playground/customization/adding-sdk-examples.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: "Adding SDK examples"
3+
description: "Display language-specific code samples alongside your API endpoints to show developers how to use your SDKs"
4+
---
5+
6+
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.
7+
8+
This property can be added to any request method and has the following schema.
9+
10+
<ParamField body="lang" type="string" required>
11+
The language of the code sample.
12+
</ParamField>
13+
14+
<ParamField body="label" type="string">
15+
The label for the sample. This is useful when providing multiple examples for a single endpoint.
16+
</ParamField>
17+
18+
<ParamField body="source" type="string" required>
19+
The source code of the sample.
20+
</ParamField>
21+
22+
Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.
23+
24+
```yaml
25+
paths:
26+
/plants:
27+
get:
28+
...
29+
x-codeSamples:
30+
- lang: bash
31+
label: List all unwatered plants
32+
source: |
33+
planter list -u
34+
- lang: javascript
35+
label: List all unwatered plants
36+
source: |
37+
const planter = require('planter');
38+
planter.list({ unwatered: true });
39+
- lang: bash
40+
label: List all potted plants
41+
source: |
42+
planter list -p
43+
- lang: javascript
44+
label: List all potted plants
45+
source: |
46+
const planter = require('planter');
47+
planter.list({ potted: true });
48+
```
49+

‎api-playground/customization/complex-data-types.mdx‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: "Complex data types"
3+
description: "Describe APIs with flexible schemas, optional properties, and multiple data formats using `oneOf`, `anyOf`, and `allOf` keywords"
4+
---
5+
6+
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.
7+
8+
## `oneOf`, `anyOf`, `allOf` keywords
9+
10+
For complex data types, OpenAPI provides keywords for combining schemas:
11+
12+
- `allOf`: Combines multiple schemas (like merging objects or extending a base schema). Functions like an `and` operator.
13+
- `anyOf`: Accepts data matching any of the provided schemas. Functions like an `or` operator.
14+
- `oneOf`: Accepts data matching exactly one of the provided schemas. Functions like an `exclusive-or` operator.
15+
16+
<Warning>Mintlify treats `oneOf` and `anyOf` identically since the practical difference rarely affects using the API.</Warning>
17+
18+
For detailed specifications of these keywords see the [OpenAPI documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).
19+
20+
<Info>The `not` keyword is currently unsupported.</Info>
21+
22+
### Combining schemas with `allOf`
23+
24+
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/).
25+
26+
```yaml
27+
org_with_users:
28+
allOf:
29+
- $ref: '#/components/schemas/Org'
30+
- type: object
31+
properties:
32+
users:
33+
type: array
34+
description: An array containing all users in the organization
35+
...
36+
components:
37+
schemas:
38+
Org:
39+
type: object
40+
properties:
41+
id:
42+
type: string
43+
description: The ID of the organization
44+
```
45+
46+
<ParamField body="org_with_users" type="object">
47+
<Expandable>
48+
<ParamField body="id" type="string">
49+
The ID of the organization
50+
</ParamField>
51+
<ParamField body="users" type="object[]">
52+
An array containing all users in the organization
53+
</ParamField>
54+
</Expandable>
55+
</ParamField>
56+
57+
### Providing options with `oneOf` and `anyOf`
58+
59+
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:
60+
61+
```yaml
62+
delivery_address:
63+
oneOf:
64+
- title: StreetAddress
65+
type: object
66+
properties:
67+
address_line_1:
68+
type: string
69+
description: The street address of the recipient
70+
...
71+
- title: POBox
72+
type: object
73+
properties:
74+
box_number:
75+
type: string
76+
description: The number of the PO Box
77+
...
78+
```
79+
80+
<ParamField body="delivery_address" type="object">
81+
<div className="mt-4 rounded-xl border border-gray-100 px-4 pb-4 pt-2 dark:border-white/10">
82+
<Tabs>
83+
<Tab title="StreetAddress">
84+
<ParamField body="address_line_1" type="string">
85+
The street address of the residence
86+
</ParamField>
87+
</Tab>
88+
<Tab title="POBox">
89+
<ParamField body="box_number" type="string">
90+
The number of the PO Box
91+
</ParamField>
92+
</Tab>
93+
</Tabs>
94+
</div>
95+
</ParamField>

‎api-playground/customization/managing-page-visibility.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: "Managing page visibility"
3+
description: "Control which endpoints from your OpenAPI specification appear in your documentation navigation"
4+
---
5+
6+
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.
7+
8+
If your pages are autogenerated from an OpenAPI document, you can manage page visibility with the `x-hidden` and `x-excluded` extensions.
9+
10+
## `x-hidden`
11+
12+
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.
13+
14+
Common use cases for `x-hidden` are:
15+
16+
- Endpoints you want to document, but not promote.
17+
- Pages that you will link to from other content.
18+
- Endpoints for specific users.
19+
20+
## `x-excluded`
21+
22+
23+
The `x-excluded` extension completely excludes an endpoint from your documentation.
24+
25+
Common use cases for `x-excluded` are:
26+
27+
- Internal-only endpoints.
28+
- Deprecated endpoints that you don't want to document.
29+
- Beta features that are not ready for public documentation.
30+
31+
## Implementation
32+
33+
Add the `x-hidden` or `x-excluded` extension under the HTTP method in your OpenAPI specification.
34+
35+
Here are examples of how to use each property in an OpenAPI schema document for an endpoint and a webhook path.
36+
37+
```json {11, 19}
38+
"paths": {
39+
"/plants": {
40+
"get": {
41+
"description": "Returns all plants from the store",
42+
"parameters": { ... },
43+
"responses": { ... }
44+
}
45+
},
46+
"/hidden_plants": {
47+
"get": {
48+
"x-hidden": true,
49+
"description": "Returns all somewhat secret plants from the store",
50+
"parameters": { ... },
51+
"responses": { ... }
52+
}
53+
},
54+
"/secret_plants": {
55+
"get": {
56+
"x-excluded": true,
57+
"description": "Returns all top secret plants from the store (do not publish this endpoint!)",
58+
"parameters": { ... },
59+
"responses": { ... }
60+
}
61+
}
62+
},
63+
```
64+
65+
```json {9, 15}
66+
"webhooks": {
67+
"/plants_hook": {
68+
"post": {
69+
"description": "Webhook for information about a new plant added to the store",
70+
}
71+
},
72+
"/hidden_plants_hook": {
73+
"post": {
74+
"x-hidden": true,
75+
"description": "Webhook for somewhat secret information about a new plant added to the store"
76+
}
77+
},
78+
"/secret_plants_hook": {
79+
"post": {
80+
"x-excluded": true,
81+
"description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)"
82+
}
83+
}
84+
}
85+
```

‎api-playground/customization/multiple-responses.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: "Multiple responses"
3+
description: "Show response variations for the same endpoint"
4+
---
5+
6+
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.
7+
8+
This property can be added to any response and has the following schema.
9+
10+
```yaml
11+
responses:
12+
"200":
13+
description: Successful response
14+
content:
15+
application/json:
16+
schema:
17+
$ref: "#/components/schemas/YourResponseSchema"
18+
examples:
19+
us:
20+
summary: Response for United States
21+
value:
22+
countryCode: "US"
23+
currencyCode: "USD"
24+
taxRate: 0.0825
25+
gb:
26+
summary: Response for United Kingdom
27+
value:
28+
countryCode: "GB"
29+
currencyCode: "GBP"
30+
taxRate: 0.20
31+
```

‎api-playground/mdx/authentication.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@ title: "Authentication"
33
description: "You can set authentication parameters to let users use their real API keys."
44
---
55

6-
## Enabling Authentication
6+
## Enabling authentication
77

8-
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.
8+
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.
99

10-
The page's authentication method will override docs.json if both are set.
10+
A page's authentication method will override a global method if both are set.
1111

12-
### Bearer Token
12+
### Bearer token
1313

1414
<CodeGroup>
1515

@@ -32,7 +32,7 @@ authMethod: "bearer"
3232

3333
</CodeGroup>
3434

35-
### Basic Authentication
35+
### Basic authentication
3636

3737
<CodeGroup>
3838

@@ -55,7 +55,7 @@ authMethod: "basic"
5555

5656
</CodeGroup>
5757

58-
### API Key
58+
### API key
5959

6060
<CodeGroup>
6161

0 commit comments

Comments
 (0)