Customer StoriesReadMe Blog

## Building Your API Reference

Chances are that if you're using ReadMe, you've got an API. In order for your developers to be able to interact with your API, a comprehensive API reference is essential! 💯

You've got a few options when it comes to how you set up your <<glossary:API Reference>>. First, head to your project dashboard and navigate down to Documentation > API Reference.

Here's a GIF highlighting how to set up your first API definition:



<p class="blank-line"></p>

## Describing Your API (OpenAPI Upload vs. Manual Editor)

You have two options when it comes to setting up your API:

  1. **Upload an OpenAPI file**: We support [OpenAPI 3.0](🔗), [OpenAPI 3.1](🔗), and [Swagger 2](🔗) API formats. If you upload an OpenAPI definition, ReadMe will take care of creating the API setting and reference docs for you! You can upload an OpenAPI definition via one of four methods:

    1. **Command Line**: using our command line tool, [`rdme`](🔗) 🔄

    2. **GitHub**: setting up the [`rdme` GitHub Action](🔗) in the repository containing your OpenAPI definition 🐙

    3. **File**: drag the OpenAPI file into ReadMe 🗃️

    4. **URL**: enter in a public URL to your OpenAPI definition 🔗

You can learn more about each of the OpenAPI upload options [here](🔗)!

  1. **Manual Editor**: you can manually describe your API using our online UI. For guidance on manually describing your API and best practices, head to [this page](🔗).

## Categories and Markdown Pages

If you import a OpenAPI definition, we will automatically create Categories, Pages and Subpages based on certain attributes of your definition. You can learn more about that [here](🔗). If you use our Manual Editor, you'll have to organize this information manually.

As a general rule of thumb, we recommend having one page per API endpoint. We also recommend categorizing your pages in a way that makes the most sense for your API and your end-users.

From the API Reference section in your dashboard you can create **Categories** to organize your pages:

<p class="blank-line"></p>



<p class="blank-line"></p>

For pages that aren't describing API endpoints, you can create basic Markdown pages (similar to pages you typically see in the Guides section). These kinds of pages are great for describing general information about your API, such as authentication, object models, or paginating through API results. For both API endpoint pages and basic Markdown pages, you can include text, imagery, code samples, and more.