We've made improvements to our two-factor authentication (2FA) implementation! Now, when you enable 2FA (or view your existing setup) in your profile settings, you have access to backup codes. Once you have 2FA enabled, these one-time use backup codes can be used to log you into ReadMe if you are unable to access 6-digit codes from your authenticator app.

🚧

Keep your backup codes safe!

Remember that these backup codes are one-time use - so if you just a few (or zero) remaining, you can generate new ones in the profile settings by clicking the View Backup Codes button. Generating new backup codes will invalidate your old ones!

If you cannot access your authenticator app and lost your backup codes, please contact us at [email protected].

Also, we're now on twofactorauth.org! 🎉

Check out our updated knowledge base for more guidance on two-factor authentication.

Today we've released some updates to our implementation of the OpenAPI 3.0 specification in our API Explorer to support common parameters for a path.

With this support, you will now be able to re-use common path parameters within the path item declaration without having to fully document them as a $ref.

For example:

"/pets/{petId}": {
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "required": true,
      "description": "The id of the pet to retrieve",
      "schema": {
        "type": "string"
      }
    }
  ],
  "delete": {
    "summary": "Delete a specific pet",
    "operationId": "deletePetById",
    ...
  },
  "get": {
    "summary": "Info for a specific pet",
    "operationId": "showPetById",
    ...
  }
}

Previously to sync a file with ReadMe, you needed to enter a URL, use our CLI tool rdme, or use our API directly. We've just added a new option for uploading your Swagger or OAS file directly into the ReadMe dashboard!

Now if you just have a spec file on your computer you can easily get it up and running in ReadMe, without installing anything or making it available via a url.

Today we've released some improvements to our code highlighting support across pages and our API Explorer!

Pages

In addition to the slew of languages we already supported, we've released improved fixes to Kotlin rendering as well as the addition of support for Dockerfile and PowerShell.

API Explorer

Similarly, we have also released the support for C, C++, Kotlin, and PowerShell to our API Explorer.

Don't see your favorite language? Let us know!

This past week we released v3.4 of our CLI tool rdme, and with it brought a heap of quality of life improvements.

Improved Documentation

We've completely overhauled our help command to allow to fully document all commands, arguments, and options. You can now access help for any command via wither rdme help <command> or rdme <command> --help.

Additionally, we've also created a number of new command groupings, which now allows us to surface similar commands on a commands help screen. For example, if you're using rdme versions and want to see other version-related things you can do, rdme versions --help will tell you about rdme versions:create, rdme versions:update, and rdme versions:delete!

Improved Error Handling

A common problem we've had with rdme was that error handling was never consistent. In one command, you might get a helpful error message, and another you receive back a raw JSON dump from our API. We've taken this as an opportunity to rework how we handle failure states to account for, and properly handle, the various ways a command may fail.

Now in v3.4+, you will receive a helpful, color-coded, error message explaining what you (or us!) maybe have done to necessitate an error state. If all else fails, and we've unfortunately failed to catch the error properly, we'll now direct you to contact our wonderful support team who can assist you.

New commands

In addition to the gamut of QOL improvements, we've also released a couple new commands:

We're proud to offer endpoints for programmatic version control! Now you can manage your project versions directly through our rdme command line interface, or RESTful requests in your application.

If you'd like to to spin up a new version in your CI pipeline for behavioral testing, you can do that too!

Command Line Interface

You can interact with the service for typical CRUD operations:

Using the CLI should be consistent with existing interactions; just use the version command! You can find all of the flags and additional documentation for the CLI here: rdme.

rdme login;
rdme versions [--key key] [--version version];

[{ _id: '5d2e58d79f94773b91a12b66',
  forked_from: '5d2d202adf89cf02e963ad0e',
  createdAt: '2019-06-24T23:13:25.571Z',
  is_deprecated: false,
  is_hidden: false,
  is_beta: true,
  is_stable: true,
  codename: 'My First ReadMe Version!',
  version: '1.0' 
 }]

rdme versions:create [--key key] --version={Version} [--fork fork] 
[--main main] [--beta beta] [--codename codename];

Version X.X.X created successfully

rdme versions:update [--key key] --version={Version} [--newVersion newVersion] 
[--main main] [--beta beta] [--codename codename] [--deprecated deprecated];

Version X.X.X updated successfully

rdme versions:delete [--key key] --version={Version};

Version X.X.X deleted successfully

RESTful Requests

You can additionally interact with the versions API as you would with any other traditional REST-oriented service. Be sure to include your authorization via your ReadMe project! Depending on the request, you can provide a selection of body data to create and modify your versions.

curl -X GET \
  https://dash.readme.io/api/v1/version \
  -u ${YOUR_TOKEN}:

curl -X GET \
  https://dash.readme.io/api/v1/version/X.X.X \
 -u ${YOUR_TOKEN}:

curl -X POST \
  https://dash.readme.io/api/v1/version \
  -u ${YOUR_TOKEN}: \
  -d '{
	"version": "NEW_VERSION",
	"from": "FORKED_VERSION",
  	"codename": string, 			//optional parameter
  	"is_stable": boolean,			//optional parameter
  	"is_beta": boolean,			//optional parameter
  	"is_hidden": boolean			//optional parameter
}'

curl -X PUT \
  https://dash.readme.io/api/v1/version/X.X.X \
 -u ${YOUR_TOKEN}: \
  -d '{
	"version": "UPDATED_VERSION",
	"codename": string, 			//optional parameter
  	"is_stable": boolean, 			//optional parameter
  	"is_beta": boolean, 			//optional parameter
  	"is_hidden": boolean, 			//optional parameter
    	"is_deprecated": boolean, 		//optional parameter
}'

curl -X DELETE \
  https://dash.readme.io/api/v1/version/X.X.X \
  -u ${YOUR_TOKEN}:

Conclusion

As an API documentation platform, we at ReadMe are always excited to contribute in the public-facing service space. Programmatic version control has been a much requested feature, and we're happy to offer and support it going forward.

We'll see you at our next Changelog entry!

Since we've been working hard on a lot of of new features, we wanted a way to announce all of the cool things we are building here at ReadMe. Since we already had Changelog functionality built into our platform, we gave it a coat of paint and new functionality to really make it shine!

Now you can embed a widget anywhere you want, and your users can see all of your posts without ever leaving the product!

Along with the widget functionality, we also added five new top-level Changelog types to enhance readability (or No Type if you're old-school and/or indecisive):

The new Changelog (and the embeddable widget) is available now. All existing Changelogs have been migrated over to the new format. Please contact support if you see any issues!

We hope these improvements empower your users with the knowledge to take advantage of your latest and greatest product updates! 🎉