Skip to content

Latest commit

 

History

History
152 lines (110 loc) · 5.93 KB

README.md

File metadata and controls

152 lines (110 loc) · 5.93 KB
Raw

📖 rdme

npm Build

rdme is the CLI wrapper for ReadMe's RESTful API. It allows you to upload and edit OpenAPI and Swagger files associated with projects you create on ReadMe. Additionally, you can sync documentation with your project, and manage project versions.

Configuration

Installation

npm install rdme

Authentication

If you authenticate rdme to your ReadMe project, we will save your API key to a local configuration file (~/.config/configstore/rdme-production.json) so you will not have to provide the --key option to commands that require it.

rdme login

rdme whoami is also available to you to determine who you are logged in as, and to what project, as well as rdme logout for logging out of that account.

Usage

If you wish to get more information about any command within rdme, you can execute rdme help <command> or rdme <command> --help. You an also execute rdme help to see a global list of commands that rdme offers.

Common rdme Options

  • --key <string>: The API key associated with your ReadMe project. You can obtain this from your dashboard, or alternatively if you log in with rdme login, we will save your API key to a local configuration file (~/.config/configstore/rdme-production.json), saving you the hassle of having to supply this argument on commands that have it.
  • --version <string>: Your project version.

OpenAPI / Swagger

ReadMe supports OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.x.

The following examples use JSON files, but we support API Definitions that are written in either JSON or YAML.

ℹ️ Note that the rdme openapi command supports both OpenAPI and Swagger API definitions. The rdme swagger command is an alias for rdme openapi and is deprecated.

Uploading a New API Definition to ReadMe

This will upload path-to-openapi.json to your project and return an ID and URL for you to later update your file, and view it in the client.

rdme openapi [path-to-file.json]

Editing (Re-Syncing) an Existing API Definition

This will edit (re-sync) an existing API definition (identified by --id) within your ReadMe project.

rdme openapi [path-to-file.json] --id={existing-id}

Uploading or Editing an API Definition in a Project Version

You can additional include a version flag, specifying the target version for your file's destination

rdme openapi [path-to-file.json] --version={project-version}
rdme openapi [path-to-file.json] --id={existing-id} --version={project-version}

Omitting the File Path

If you run rdme within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. We will then look for a file with the following names, and upload that: openapi.json, openapi.yaml, swagger.json, and swagger.yaml.

rdme openapi

Validating an API Definition

You can also perform a local validation of your API definition without uploading it to ReadMe, which can be useful when constructing or editing your API definition.

rdme validate [path-to-file.json]

Docs

Syncing a Folder of Markdown Docs to ReadMe

rdme docs path-to-markdown-files --version={project-version}

Edit a Single ReadMe Doc on Your Local Machine

rdme docs:edit <slug> --version={project-version}

Versions

Get All Versions Associated With Your Project

rdme versions

If you wish to see the raw JSON output from our API in this response, supply the --raw flag.

Get All Information About a Particular Version

rdme versions --version={project-version}

If you wish to see the raw JSON output from our API in this response, supply the --raw flag.

Create a New Version

rdme versions:create <version> | --version={project-version}
Create a New Version

If you wish to automate the process of creating a new project version, and not have the CLI prompt you for input, you can do so by supplying the necessary flags to versions:create.

For example:

rdme versions:create <version> | --version={project-version} --fork={version-fork} --main={boolean} --beta={boolean} --isPublic={boolean}

See rdme versions:create --help for a full list of flags.

Update a Version

rdme versions:update --version={project-version}

Like versions:create, if you wish to automate this process and not be blocked by CLI input, you can supply the necessary flags to this command. See rdme versions:update --help for more information.

Delete a Version

You can remove a specific version from your project, as well as all of the attached specs

rdme versions:delete --version={project-version}

Open Your ReadMe Project in Your Browser

If you are logged in, this will open the project in your browser:

rdme open

Future

We are continually expanding and improving the offerings of this application as we expand our public API and are able. Some interactions may change over time, but we will do our best to retain backwards compatibility.