Skip to main content

Export your specification to Readme

What you'll need to know#

To integrate with Readme, you'll need the following information:

  • Readme username and password to log in with the rdme command line tool (we'll install that later).
  • Readme project subdomain such as your-api-project.

Preparing your Readme setup

Once you have an active project, there's no further setup required on your Readme account.

Integrating Readme with Optic scripts

Scripts are defined in your project's optic.yml file. We'll add a script definition to call the Readme CLI and update your documentation:

optic.yml
name: "todo-js" tasks:  start:    command: node server.js --port $PORT    inboundUrl: http://localhost:3001    scripts:  readme:    command: rdme login && rdme swagger $OPENAPI_JSON    dependsOn: rdme    install: npm install --global rdme

Running your Optic Script for the first time#

To ensure the dependency is installed, run:

api scripts readme --install

This will check for the Readme CLI rdme, and if it isn't found, install it. Once installed, Optic will generate an up to date OpenAPI file, log you in to Readme, and upload the latest specification.

[optic] Found Script readmeChecking bin dependencies Requiring ["rdme"]... Missing dependencies[optic] Some bin dependencies are missing ["rdme"]. falseRunning install command: npm install --global rdme ... ⣟...+ rdme@4.0.0Running install command: npm install --global rdme ... Success!
[optic] Generated OAS .../.optic/generated/openapi.json[optic] .../.optic/generated/openapi.yaml
Running command: rdme login && rdme swagger .optic/generated/openapi.jsonEmail: <email>Password: ⣟⣟⣟⣟⣟⣟⣟⣟⣟⣟⣟⣟⣟⣟⣟Project subdomain: <your-api-project>Successfully logged in as <email> to the <your-api-project> project.✔ Would you like to use an existing version or create a new one to associate with your OAS file? · update✔ Select your desired version · 1.0You've successfully uploaded a new Swagger file to your ReadMe project!
    https://dash.readme.com/project/<your-api-project>/v1.0/refs/apitodos
To update your Swagger or OpenAPI file, run the following:
    rdme openapi FILE --key=<key> --id=60fadcc5f900ff000f9b1365
tip

The Readme CLI will suggest that you run the command with a key parameter. That is not necessary - you don't need to make any changes to your optic.yml file. If you wish, you may update your optic.yml to use this flag and remove the need to run the login command every time, though keep in mind that this is a secret key tied to your identity. Follow your organization's best practices for managing keys and identities, such as having every team member store their own key value in a local environment variable on their workstation or using secrets in your CI provider, such as GitHub Secrets. Don't commit this key to your repository!

Running your Optic Script generally#

You don't need to run your scripts command with the --install flag every time. Once installed, you can run:

api scripts readme

You will be prompted to log in, and your latest specification will be uploaded to Readme. If you opt to use the Readme --key flag, you can even have this run automatically such as in your CI pipeline on merges. Let us know if we can help you integrate your Optic Script further.