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 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:

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!

2. 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:

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.

Additional Customizations

Simple Mode

Simple Mode allows you to show api as an option in the Node language library to your end developers who are visiting your developer hub's API reference.

If you'd like to enable it, head to the API Reference section within the Appearance section of your project dashboard, and check the box for Simple Mode. If you'd like to disable this feature, uncheck the box.

Default Handling

When enabled, any default values defined in your API spec will be used to populate your request data in the API Explorer on page load, regardless of the parameter being marked as required. For example, this operation will populate the petName field in the API Explorer with "Buster" even though it is not marked as required:

{
  "/pet": {
    "get": {
      "summary": "Find pet by Name",
      "description": "Returns a single pet",
      "operationId": "getPetByName",
      "parameters": [
        {
          "name": "petName",
          "in": "body",
          "description": "Name of pet to return",
          "required": false,
          "schema": {
            "type": "string",
            "default": "Buster",
            "example": "Apollo"
          }
        }
      ]
    }
  }
}

When disabled, default values will only be used to populate the form field and code sample if the parameter is marked as required. If the operation has an example value or examples object defined, we'll use that value as a placeholder in the API Explorer form, but it will not populate the code sample.

For example, using the same operation as above, the petName field in the API Explorer will contain a placeholder example value "Apollo", but the code sample will not be pre-filled:

If the parameter is not marked as required, then the enduser must explicitly select the default value from the dropdown when the field is active:

To configure the Default Handling setting, go to your Project Dashboard > Appearance > API Reference Configuration.

Raw JSON Editor

📘

Enterprise Only

The raw JSON editor setting is only available to enterprise customers. Contact us at [email protected] if you're interested in a demo!

For most APIs, the forms on API reference pages are the most intuitive way to enter in body parameters for API requests. In the petstore example below, the following form data:

...will yield JSON that looks like this:

{ "complete": false, "id": 123 }

However, your API users may prefer to write their request body JSON by hand. That's where enabling the Raw JSON Editor setting may be useful. When enabled, your users will have the ability to edit their request body via a raw JSON editor.

For endpoints that support JSON request bodies, you can click the "JSON Editor" icon below your code sample (see annotation #1 below) and a raw JSON editor will appear. It will validate your JSON input and update your code sample as you type.

To configure this setting, go to your Project Dashboard > Appearance > API Reference Configuration.