What Is OpenAPI (Formerly Known As Swagger)?
From the OpenAPI Specification repository:
The OpenAPI Specification (OAS) is a community-driven open specification within the OpenAPI Initiative... [that] defines a standard, programming language-agnostic interface description for REST APIs.
Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases.
The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service β the service being described may not even be owned by the creator of its description.
The OpenAPI Specification was developed privately for several years under the name Swagger. Back when it was known as Swagger 2.0, the specification was donated to the OpenAPI Initiative and became an open standard in 2015. Version 3.0.0 was released under the name OpenAPI Specification 3.0.0.
You can read about the revision history here and read about the differences between Swagger 2.0 and OAS 3.0 on our blog.
We currently only support Swagger 2.0, OAS 3.0.0, 3.0.1, 3.0.2, and 3.0.3.
The API Explorer
The API Explorer is our open-source interactive API reference. Based on your OpenAPI document, the API Explorer will generate reference guides that include working code examples and the ability to make authenticated API requests directly within the documentation.
Importing an OpenAPI Document
You can import your OpenAPI document by going to the APIs section and clicking Add your first API or Add More Endpoints. You will have three options for OpenAPI Upload.


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


If there are any errors with your document, our validator will notify you.
The link you supply to us must be publicly accessible and in the JSON or YAML formats.
If you don't yet have a OpenAPI document, you can build one using Swagger Inline.
CLI
You can import your OpenAPI document locally using our rdme
CLI tool:
npm install rdme -g
rdme login
rdme swagger [path-to-file.json]
The CLI tool will check that the version in your OpenAPI document has a matching version in your ReadMe project, which is where it will be uploaded. You can read more about how the tool handles versions here.
File Upload
You can upload a local file with the file upload feature by clicking on this white box - it will bring up your file finder for you to select your OpenAPI document.


Direct Upload
You can upload the file directly with the available prompts on the screen.
Re-syncing an OpenAPI Document
If you uploaded your OpenAPI document via URL, you can simply go to the APIs section, click re-sync next to your API definition and ReadMe will re-fetch the original URL that you provided.
For the rdme
CLI tool, run the same command as before but append the unique API definition ID. You can obtain this ID by clicking edit on the API definition on your project API definitions page.
rdme swagger [path-to-file.json] --id={existing-id}
For more information on re-syncing, please read our docs on Re-syncing Your OpenAPI Document
Editing an OpenAPI Document
You can switch to a different OpenAPI/Swagger file by clicking on the edit button and following the instructions.
Adding Markdown Content
You can add additional Markdown content to each individual file that is imported. These changes will remain even after you re-sync as long as you do not change the operationId
or remove the import.
If you add additional Markdown content, be aware that it will be tied to the
operationId
of that specific imported API definition. If theoperationId
, or file, is removed, your additional content will also be removed.
Updated about a month ago