You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: api-playground/openapi-setup.mdx
+39-26Lines changed: 39 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,11 @@ We recommend the following resources to learn about and construct your OpenAPI d
22
22
-[The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint openapi-check <openapiFilenameOrUrl>`.
23
23
24
24
<Note>
25
-
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.
25
+
Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information
26
+
is applicable to v3.1. For more information on the differences between v3.0
@@ -53,34 +57,34 @@ To enable authentication in your API documentation and playground, configure the
53
57
<Steptitle="Define your authentication method.">
54
58
Add a `securitySchemes` field to define how users authenticate.
55
59
56
-
This example shows a configuration for bearer authentication.
60
+
This example shows a configuration for bearer authentication.
57
61
58
-
```json
59
-
{
60
-
"components": {
61
-
"securitySchemes": {
62
-
"bearerAuth": {
62
+
```json
63
+
{
64
+
"components": {
65
+
"securitySchemes": {
66
+
"bearerAuth": {
63
67
"type": "http",
64
68
"scheme": "bearer"
65
-
}
66
69
}
67
70
}
68
71
}
69
-
```
72
+
}
73
+
```
70
74
71
75
</Step>
72
76
<Steptitle="Apply authentication to your endpoints.">
73
77
Add a `security` field to require authentication.
74
78
75
-
```json
76
-
{
77
-
"security": [
78
-
{
79
-
"bearerAuth": []
80
-
}
81
-
]
82
-
}
83
-
```
79
+
```json
80
+
{
81
+
"security": [
82
+
{
83
+
"bearerAuth": []
84
+
}
85
+
]
86
+
}
87
+
```
84
88
85
89
</Step>
86
90
</Steps>
@@ -114,7 +118,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
114
118
"metadata": {
115
119
"title": "List all users",
116
120
"description": "Fetch paginated user data with filtering options",
117
-
"og:title": "Display a list of users",
121
+
"og:title": "Display a list of users"
118
122
}
119
123
},
120
124
"parameters": [
@@ -132,7 +136,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
132
136
133
137
Add content before the auto-generated API documentation using `x-mint: content`:
134
138
135
-
```json {6-13}
139
+
```json {6-8}
136
140
{
137
141
"paths": {
138
142
"/users": {
@@ -223,7 +227,9 @@ Generated endpoint pages have these default metadata values:
223
227
-`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.
224
228
225
229
<Tip>
226
-
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.
230
+
To exclude specific endpoints from your auto-generated API pages, add the
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:
275
281
```
276
282
277
283
<Note>
278
-
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.
284
+
The `directory` field is optional and specifies where generated API pages are
285
+
stored in your docs repo. If not specified, defaults to the `api-reference`
286
+
directory of your repo.
279
287
</Note>
280
288
281
289
### Selective endpoints
@@ -369,7 +377,9 @@ When you reference an OpenAPI operation this way, the name, description, paramet
369
377
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.
370
378
371
379
<Note>
372
-
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.
380
+
This approach works regardless of whether you have set a default OpenAPI spec
381
+
in your navigation. You can reference any endpoint from any OpenAPI spec by
382
+
including the file path in the frontmatter.
373
383
</Note>
374
384
375
385
If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`.
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.
412
+
The method and path must exactly match the definition in your OpenAPI
413
+
specification. If the endpoint doesn't exist in the OpenAPI file, the page
414
+
will be empty.
403
415
</Note>
404
416
405
417
### Autogenerate `MDX` files
@@ -428,6 +440,7 @@ The scraper generates:
428
440
```
429
441
430
442
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.
0 commit comments