Overview

Creating a comprehensive API reference starts with your OpenAPI Specification (OAS). ReadMe makes it simple to transform your existing OAS file into beautiful, interactive documentation that your developers will actually enjoy using.

Getting Started: Adding Your API Specification

To add your API specification to ReadMe:

1. Navigate to your project and click on API Reference from the editor UI
2. You'll see three options for creating your API reference:
   • Upload File (.yaml or .json)
   • Import from URL
   • Build an API definition from scratch

Option 1: Upload Your OAS File

If you already have an OpenAPI specification file in YAML or JSON format:

1. Click Upload File
2. Select your .yaml or .json file
3. ReadMe will parse your specification and generate your API reference automatically

Option 2: Import from URL

If your OAS file is hosted online:

1. Click Import from URL
2. Enter the URL where your specification is hosted
3. Click Import
4. ReadMe will fetch and parse your specification

Option 3: Build from Scratch

Don't have an OAS file yet? No problem!

1. Click Start Building in the "Build an API definition from scratch" section
2. Use our intuitive API Designer (formerly called manual editor) to create your API specification
3. Add endpoints, parameters, response codes, and examples without writing any YAML or JSON

Managing Your API Definitions

After successfully adding your specification, you'll see it in the left navigation panel. Here's how to manage it:

Viewing Your API Definitions

1. Click on API Definitions to see a list of all your uploaded specifications
2. Each definition shows:
   • Name of your API
   • Last update timestamp
   • Import method (File Upload, URL, etc.)

Adding Additional API Definitions

Need to add another API or version?

1. Click the + Add button in the top right of the API Definitions page
2. Choose your preferred import method again (Upload, URL, or Build)

Managing Editing Permissions

To prevent accidental changes to your specification:

1. Click the Gear icon next to the Add button
2. Toggle the Allow Editing switch off
3. This is useful when you manage your OAS file externally and want to prevent changes within ReadMe

Editing Your API Definition

To make changes to your specification:

1. Find your API definition in the list
2. Click the Ellipses (three dots) menu
3. Choose from these options:
   • Edit Definition: Make changes to your API configuration
   • View OAS: Open your raw OpenAPI Specification in a new tab
   • Edit OAS File: Edit the raw OpenAPI Specification directly in the dashboard
   • Replace OAS: Upload a new version of your specification
   • Delete: Remove this API definition

Editing an OAS File

• OAS files are validated on upload or when editing from ReadMe.
• Files that were uploaded as YAML files are converted to JSON.
• When syncing to GitHub or GitLab, changes you make to your OAS file will be synced to your connected repository.

Safeguards and Permissions

• Standard edit permissions apply. The OAS editor lives on the API Definitions page and is subject to the same permission checks as any other content edit. On Enterprise plans, Editors without merge access cannot edit a version directly.
• Project-level kill switch. The Allow Editing toggle (found in the gear menu on the API Definitions page) can disable in-UI OAS editing entirely. This is useful when you manage your OAS file externally (e.g., generated or synced from another source) and want to prevent changes within ReadMe. See Managing Editing Permissions for details.
• Changes go through branches and review. Edits made on a branch are written to that branch, while edits made on the main version are written directly to the main version. Enterprise customers who require review or restrict merge to admins get that protection automatically. See Branches and Reviews for more information.
• Live validation prevents saving broken specs. Edits are validated against the same pipeline that guards real uploads, so the editor always reflects what a save would enforce. The Save button is disabled while the contents are known to be invalid.
• Changes are recoverable via Git. Since OAS files are Git-backed, you can revert any changes made to the API Reference section through Git using git revert.

Editing API Settings

When editing your API definition, you can configure:

1. API Title: The display name of your API
2. Target Host URL: The base URL for making API calls
3. Authentication Type: Configure how developers will authenticate with your API
   • None
   • API Key
   • Basic
   • Bearer

Best Practices

• Keep it updated: Whenever your API changes, update your specification to ensure your documentation stays accurate
• Use detailed descriptions: Take advantage of the description fields in your OAS file to provide context
• Include examples: Add request and response examples to help developers understand your API
• Disable editing if you manage your specification externally to prevent conflicting changes
• Use versioning for major API changes to help developers migrate smoothly

By following these steps, you'll create a professional, interactive API reference that helps developers succeed with your API.