Adding Your API Reference

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!

  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:

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"
With **Default Handling** enabled, the `default` value "Buster" is used to populate the API Explorer form and the auto-generated code sample, even when the parameter isn't marked as `required`.

With Default Handling enabled, the default value "Buster" is used to populate the API Explorer form and the auto-generated code sample, even when the parameter isn't marked as required.

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:

With **Default Handling** disabled, the `example` value "Apollo" is used as a **placeholder** in the API Explorer form.

With Default Handling disabled, the example value "Apollo" is used as a placeholder in the API Explorer form. Note that the code sample is not populated.

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:

The `default` value must be selected from the dropdown

The default value must be selected from the dropdown.

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:

A form in the API reference, where the `id` integer value is "123" and the `complete` boolean value is "false".

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

A raw JSON code editor, with "{ "id": 123 }" entered in the editor. The cURL code snippet above includes this JSON as its request body.

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