This page describes how to set up an API reference section using an OpenAPI definition. We support JSON and YAML formats and our uploader includes comprehensive file validation. Check out our docs on our OpenAPI support for more information.

Describe Your API via OpenAPI Upload

You can import your OpenAPI definition by going to the API Reference section with your project dashboard and clicking Add your first API, + API, or Add more endpoints.

There are four options for how to upload your OpenAPI file.

Upload via Command Line (Recommended ✨)

By setting up a workflow with ReadMe's official command line tool, rdme, you can automatically sync changes you make to your OpenAPI definition to your ReadMe docs! Check out our docs for full setup and usage instructions.

Upload via GitHub (Recommended ✨)

Similar to the CLI usage above, you can set up workflows for syncing your OpenAPI definition to ReadMe every time you push new changes to your OpenAPI definition in GitHub. You'll also be using rdme for this, which doubles as ReadMe's official GitHub Action! Check out our rdme docs, which contain setup instructions and several usage examples.

Upload via File

You can upload a local file with the file upload feature by clicking on the white box, as shown in the image below. It will bring up your file finder for you to select your OpenAPI document.

⚠

This Method Does Not Sync Automatically!

Anytime you make a change to your API file, you'll need to re-upload the file to your API reference in ReadMe in order for the changes to sync in ReadMe.

Upload via URL

You can provide a link to your publicly hosted OpenAPI document:

If you don't yet have a OpenAPI document, you can build one using Swagger Inline.

🚧

A Publicly Accessible Link is Required!

The link you supply to us must be publicly accessible.

🚧

This Method Does Not Sync Automatically!

Anytime you make a change to your API file, you'll need to re-sync the file to your API reference in ReadMe in order for the changes to sync in ReadMe.

Direct Upload

You can upload the file directly with the available prompts on the screen.