rdme

    7.5.0 • Public • Published

    📖 rdme

    npm Build

    rdme is ReadMe's official command-line interface (CLI) and GitHub Action wrapper. It allows you to sync OpenAPI and Swagger definitions with projects you create on ReadMe. You can also access other parts of ReadMe's RESTful API, including syncing Markdown documentation with your project and managing project versions.

    Configuration

    Setup

    These setup instructions are for CLI usage only. For usage in GitHub Actions, see GitHub Actions below.

    We recommend installing rdme in your project rather than doing a global installation so you don't run into unexpected behavior with mismatching versions. We also suggest using the --save-dev flag since rdme is typically used as part of a CI process and is unlikely to be running in your production application:

    npm install rdme --save-dev

    Once installed in your project, we recommend using npx (which is included if you have npm installed) to prefix all of your CLI commands. For example:

    npx rdme validate [file]

    To ensure you're getting the latest features and security updates, we recommend using a tool like Dependabot to keep rdme (and your other dependencies) up-to-date.

    Authentication

    For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing your project API key via the --key option (instead of the configuration file authentication described below).

    For local CLI usage with a single project, you can authenticate rdme to your ReadMe project. This 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

    If you have two-factor authentication (2FA) enabled on your account, you'll need to pass in the --2fa option:

    rdme login --2fa

    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. Note that most of the commands below require API key authentication, even though the --key flag is omitted from the examples. See the Authentication section above for more information.
    • --version <string>: Your project version. See our docs for more information.

    GitHub Actions

    For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out our docs.

    For usage in GitHub Actions, create a new GitHub Workflow file in the .github/workflows directory of your repository and add the following steps to your workflow:

    - uses: actions/checkout@v3
    - uses: readmeio/rdme@XX
      with:
        rdme: [your command here]

    The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command:

    rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID

    To execute this command via GitHub Actions, the step would look like this:

    - uses: readmeio/rdme@XX
      with:
        rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID

    Note that the @XX in the above examples refers to the version of rdme. You can see examples featuring the latest version in our docs. We recommend pointing to a fixed version, as opposed to pointing to something like the main branch, which could unexpectedly break your workflows. We also recommend configuring Dependabot to keep your actions up-to-date.

    OpenAPI / Swagger

    ReadMe supports OpenAPI 3.1, OpenAPI 3.0, 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. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.

    rdme openapi [path-to-file.json] --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
    • openapi.yml
    • swagger.json
    • swagger.yaml
    • swagger.yml
    rdme openapi

    Override the Working Directory

    By default, rdme bundles all references with paths based on the directory that rdme is being run in. You can override the working directory using the --workingDirectory option, which can be helpful for bundling certain external references (see here for an example file).

    rdme openapi petstore.json --workingDirectory=[path to directory]

    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

    The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter.

    Passing in a path to a directory will also sync any Markdown files that are located in subdirectories.

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

    This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode in our docs.

    Edit a Single ReadMe Doc on Your Local Machine

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

    Syncing a Single Markdown File to ReadMe

    rdme docs:single path-to-markdown-file --version={project-version}

    Changelogs

    Syncing a Folder of Markdown to ReadMe

    The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter.

    Passing in a path to a directory will also sync any Markdown files that are located in subdirectories.

    rdme changelogs path-to-markdown-files

    This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode in our docs.

    Syncing a Single Markdown File to ReadMe

    rdme changelogs:single path-to-markdown-file

    Custom Pages

    Syncing a Folder of Custom Pages to ReadMe

    Custom Pages has support for both Markdown and HTML files. These files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter.

    Passing in a path to a directory will also sync any HTML/Markdown files that are located in subdirectories.

    rdme custompages path-to-markdown-files

    This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode in our docs.

    Syncing a Single Custom Page to ReadMe

    rdme custompages:single path-to-markdown-file

    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}

    Categories

    Get All Categories Associated to Your Project Version

    rdme categories --version={project-version}

    Create a New Category for your Project Version

    rdme categories:create <title> --categoryType={category-type} --version={project-version}

    categoryType is required and must be set to either guide or reference

    If you want to prevent the creation of a duplicate category with a matching title and categoryType, supply the --preventDuplicates flag.

    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.

    Keywords

    none

    Install

    npm i rdme

    DownloadsWeekly Downloads

    26,067

    Version

    7.5.0

    License

    MIT

    Unpacked Size

    227 kB

    Total Files

    54

    Last publish

    Collaborators

    • dannobytes
    • gkoberger
    • domharrington
    • mjcuva
    • kanadgupta
    • jonursenbach
    • rafegoldberg
    • dashron
    • iliast
    • owlbert