We just released a GitHub Action for automatically syncing an API Spec file directly from a GitHub repo! GitHub Actions are packages you can include in your GitHub configuration that run whenever certain events happen--such as pushing code to master, opening a pull request, and many more.

With our GitHub Actions, you can automatically sync a Swagger or OAS file every time a commit is pushed to master, meaning you no longer have to worry about keeping your docs up to date.

It's super easy to get started! After you join the GitHub Actions beta at https://github.com/features/actions (GitHub just announced it will be generally available November 13th), you just need to copy one file to your repo, add in your ReadMe settings, and that is it!

You can read the docs here to get started: https://docs.readme.com/docs/automatically-sync-api-specification-with-github

Happy Halloween and happy syncing!

We’ve made a lot of changes to our dashboard to make things easier to find, and added more information about your project and ReadMe to the Project Dashboard! For more information about these changes, you can read our blog post: https://blog.readme.io/dashboard-fall-cleaning

Project Dashboard

The Project Dashboard is now a more dynamic place! You can see a quick glance of metrics for your project or API, as well as information about new features, tips and tricks, and higher level blog posts about documentation and APIs.

There are always cool new things being released and want to make sure we spread the word on all of it! This section will have all of the new features we release as well as tips and tricks on how each project can give the best documentation experience possible to their users. So stay tuned to that space and you are bound to learn something new!

Navigation Changes

We made changes to navigation in our dashboard to make it easier to reach the things used frequently. There are three main sections to the new sidebar: settings, content, and metrics. All configuration for your project will live in the top group with all settings that are usually setup once in the Configuration section.

The middle of the new sidebar contains all of the pages that contain the content. Each page maps to a different section of your public documentation and from there you can write content and modify settings for each. We’ve moved API Settings into the API Reference section so you can import an OAS file and edit the created pages all within the same place!

Lastly is all of your metrics, either about your documentation or data about your API usage (if you’ve setup Developer Metrics).

We hope these changes make it easier to get around. Don’t forget, you can always click the search button at the bottom of the sidebar (or press cmd/ctrl+k) to search for what you are looking for!

We have rolled out API endpoints for Changelog and Custom Pages! Starting today, you can programmatically view and make changes to your data for these two ReadMe modules.

Check out our API Reference for more info!

Today, we are fulfilling a much-needed customer feature request: customizing page metadata with an image, title, and description. You'll be able to customize the metadata with custom text and images using the new metadata editor modal.

Here are some samples of how cards look like on Twitter, Slack, and LinkedIn

Here is how you can start using it:

1. Go to a page/custom page/changelog of your choosing
2. Click on the downward chevron next to the "Update Doc" button (on the top right)
3. Click on "Edit Metadata"
4. Fill in the optional items and click on "Save"

To find out more about what this can do, you can check out our docs on it!

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!

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:

<tr>
  <td>
    rdme versions:create
  </td>
  <td>
    Create a new version: Create a new version within your target project. Choose the version to fork from, make it beta, public, or even promote it to your main version.
  </td>
</tr>

<tr>
  <td>
    rdme versions:update
  </td>
  <td>
    Update a version: Allows you to change the beta and public status of a version, codename subtext, deprecate it or make it your main.
  </td>
</tr>

<tr>
  <td>
    rdme versions:delete
  </td>
  <td>
    Delete a version (if not it's not your main!).
  </td>
</tr>

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!