Skip to content

Simplify Quickstart and Related Documentation for Better Developer Experience #442

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Simplify Quickstart and Related Documentation for Better Developer Experience #442

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 14 additions & 24 deletions advanced/subpath/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,20 @@ title: "Cloudflare"
description: "Host documentation at a /docs subpath using Cloudflare Workers"
---

## Create Cloudflare Worker
## Setup Guide

Navigate to the `Workers & Pages > Create application > Create worker`. You
should be able to presented with the following screen where you can create a new
Cloudlfare worker.
1. Create a Worker
- Go to `Workers & Pages > Create application > Create worker`
- Create a new worker from the dashboard

<Frame>
<img alt="Create a Cloudflare worker" src="/images/cloudflare/worker.png" />
</Frame>

### Add custom domain

Once the worker is created, click `Configure worker`. Navigate to the worker
`Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain
into the list - we recommend you add both the version with and without `www.`
prepended to the domain.
2. Configure Domain
- Go to `Configure worker > Settings > Triggers`
- Add your domain via `Add Custom Domain`
- Add both `domain.com` and `www.domain.com` versions

<Frame>
<img
Expand All @@ -27,23 +25,16 @@ prepended to the domain.
/>
</Frame>

If you have trouble setting up a custom subdirectory,
[contact our support team](mailto:[email protected]) and we'll walk you through
upgrading your hosting with us.

### Edit Worker Script

Click on `Edit Code` and add the following script into the worker's code.
3. Deploy Code
- Click `Edit Code`
- Paste the worker script below
- Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values
- Click `Deploy`

<Frame>
<img alt="Cloudflare edit code" src="/images/cloudflare/edit-code.png" />
</Frame>

<Tip>
Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and
`CUSTOM_URL` with your website's base URL.
</Tip>

```javascript
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event.request));
Expand Down Expand Up @@ -76,5 +67,4 @@ async function handleRequest(request) {
}
```

Click on `Deploy` and wait for the changes to propagate (it can take up to a few
hours).
Changes may take a few hours to propagate. Need help? [Contact support](mailto:[email protected]).
35 changes: 15 additions & 20 deletions api-playground/mdx/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,26 @@
---
title: 'MDX Setup'
description: 'Generate docs pages for your API endpoints using MDX'
description: 'Configure API endpoints with MDX'
---

Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
Set up your API documentation using `mint.json` configuration and MDX files. This generates an interactive API playground with request/response examples.

<Steps>
<Step title="Configure your API">
In your `mint.json` file, define your base URL and auth method:
<Step title="Set up mint.json">
Add your API configuration to `mint.json`:

```json
{
"api": {
"baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
"baseUrl": "https://mintlify.com/api",
"auth": {
"method": "bearer" // options: bearer, basic, key.
"method": "bearer" // Available: bearer, basic, key
}
}
}
```

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:

To hide the API playground, use:
```json
{
"api": {
Expand All @@ -32,12 +31,11 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
}
```

Find a full list of API configurations [here](/settings/global#api-configurations).
See all API options in our [configuration guide](/settings/global#api-configurations).
</Step>

<Step title="Create your endpoint pages">

Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
<Step title="Create endpoint pages">
For each endpoint, create an MDX file with:

```md
---
Expand All @@ -46,20 +44,17 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
---
```

You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:

For path parameters, use `{}`:
```bash
https://api.example.com/v1/endpoint/{userId}
```

<Note>

If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.

With `baseUrl` configured, you can use relative paths like `/v1/endpoint`
</Note>
</Step>

<Step title="Add your endpoints to your docs">
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
<Step title="Add to navigation">
Add your endpoint pages to the `navigation` field in `mint.json`. [Learn more](/settings/navigation)
</Step>
</Steps>
</Steps>
151 changes: 25 additions & 126 deletions api-playground/openapi/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,150 +3,49 @@ title: "OpenAPI Setup"
description: "Reference OpenAPI endpoints in your docs pages"
---

## Add an OpenAPI specification file
## Quick Setup

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+.
1. Have a valid OpenAPI 3.0+ spec file (JSON or YAML)
2. Add the `openapi` field to your `mint.json`:

## 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.

**Example with Anchors:**

```json {5}
```json
{
"anchors": [
{
"name": "API Reference",
"openapi": "/path/to/openapi.json",
"url": "api-reference",
"icon": "square-terminal"
"openapi": "/path/to/openapi.json", // Local file path or URL
"url": "api-reference"
}
]
}
```

![](/images/anchors-autogeneration-anchors.png)

**Example with Tabs:**

```json {6}
{
"tabs": [
{
"name": "API Reference",
"url": "api-reference",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```

![](/images/autogeneration-with-tabs.png)

<Tip>To validate your OpenAPI spec, you can use this command: <br/>`mintlify openapi-check <openapiFilenameOrUrl>`</Tip>


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 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 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).&#x20;

![](/images/elevenlabs-mdx-autogeneration-example.png)
That's it! Mintlify will auto-generate API pages for each endpoint.

### Autogenerate files
<Tip>Validate your spec with: `mintlify openapi-check <openapiFilenameOrUrl>`</Tip>

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.
## Custom API Pages

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.

```bash
npx @mintlify/scraping@latest openapi-file <path-to-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.
Need more control? Create custom MDX pages for your endpoints:

1. Auto-generate MDX files:
```bash
npx @mintlify/scraping@latest openapi-file <path-to-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/global#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.

<Note>
If your OpenAPI document is invalid, the files will not autogenerate.
</Note>

### 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.

<Snippet file="api-playground/openapi.mdx" />

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.

<CodeGroup>
```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
---
```
</CodeGroup>

<br />

<Note>
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.
</Note>

## 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:
2. Or create them manually:
```md
---
title: "Get users"
openapi: "/path/to/openapi.json GET /users"
---
```

<CodeGroup>
```md Example
---
openapi-schema: OrderItem
---
```
## Schema Pages

```md Format
---
openapi-schema: "schema-key"
---
```
</CodeGroup>
Create pages for OpenAPI schemas:
```md
---
openapi-schema: SchemaName
---
```
31 changes: 16 additions & 15 deletions api-playground/openapi/writing-openapi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,28 +5,29 @@ description: "Use OpenAPI features to enhance your Mintlify docs"

## 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://apitools.dev/swagger-parser/online/) for debugging your OpenAPI document
- [Swagger's Editor](https://editor.swagger.io/) for seeing examples in action
Need help writing OpenAPI docs? Here are essential resources:
- [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/about/) - Learn OpenAPI syntax
- [OpenAPI v3.1.0 Spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) - Official documentation
- [Validator](https://apitools.dev/swagger-parser/online/) - Debug your OpenAPI docs
- [Swagger Editor](https://editor.swagger.io/) - See live examples

<Note>
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).
Most examples use OpenAPI v3.0, but they work with v3.1. See the key differences [here](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0).
</Note>

## Specifying the URL for your API
## Base URLs

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/).
Set your API's base URL using the `servers` field. This enables features like the API Playground. Multiple servers will show as a dropdown in the playground. Without a server URL, the playground runs in simple mode.

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.
Need different URLs for specific endpoints? You can override the server URL at the path or operation level.

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.
## Authentication

## Specifying authentication
Configure API authentication using `securitySchemes` and `security` fields. OpenAPI supports:
- Basic auth
- Bearer tokens
- API keys

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 Playground automatically adds auth fields based on your security config. You can set different auth methods for specific endpoints by overriding the security field at the operation level.

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.
Check out [Swagger's auth docs](https://swagger.io/docs/specification/authentication/) for examples.
8 changes: 6 additions & 2 deletions integrations/analytics/amplitude.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@
title: "Amplitude"
---

Add the following to your `mint.json` file to send analytics to Amplitude.
To track user analytics with Amplitude:

1. Add your Amplitude API key to `mint.json`:

<CodeGroup>

Expand All @@ -14,7 +16,7 @@ Add the following to your `mint.json` file to send analytics to Amplitude.
}
```

```json Example
```json Example with API key
"analytics": {
"amplitude": {
"apiKey": "76bb138bf3fbf58186XXX00000"
Expand All @@ -23,3 +25,5 @@ Add the following to your `mint.json` file to send analytics to Amplitude.
```

</CodeGroup>

That's it! Your docs will now send page views to Amplitude.
Loading
Loading