To integrate with Readme, you'll need the following information:
- Readme username and password to log in with the
rdmecommand line tool (we'll install that later).
- Readme project subdomain such as
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:
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
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 ... ⣟...+ email@example.comRunning 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
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!
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.