Documenting Microservices in ReadMe

Gregory Koberger -

Many companies are breaking larger codebases into microservices, so different teams can work on parts of the site at different paces. They're like APIs, except for an internal audience. Like any API, they need to be documented!

While ReadMe is heavily used for large external projects, many of our customers are using it to document internal microservices.

Multiple APIs

ReadMe allows you to add multiple Swagger / OpenAPI Specs to your reference docs. So, if you have multiple Swagger files, you can put as many as you want on there.

However, there’s an issue: too many, and the page becomes slow and impossible to find anything. So, we have a feature where you can put each Swagger file on its own separate page. So, if you have 5 microservices, you’d have a dropdown to switch between them.

We’re going to make this a feature for everyone soon, however currently you have to email support@readme.io to have it enabled.

Authentication

You’ll want to keep out prying eyes, of course! ReadMe comes with a few different options:

  • Global password: A shared password that anyone can use to access the docs. It’s the simplest to set up, and the most flexible option.
  • Admins only: This means that the only people who can access your docs are “admins” that you add. Almost as easy as a global password, and easy to revoke access!
  • OAuth/etc: Sometimes you want more fine-grained control. Our Enterprise product has the ability to have read-only accounts, OAuth logins, and more. Contact us for more details!

Auto-uploading

Lastly, you’ll probably want to automate the documenting of microservices, often in a build process. We have a command line tool, rdme, that makes this easy!

When you add a new OpenAPI file in the UI, it will give you the option to do it via command line. By integrating this in your build process, you’ll be able to automate uploading of your JSON or YAML file. We also have direct API access if that’s better for you.

Lastly, we developed something called Swagger Inline, which makes it really easy to document your microservice right from the code. You can use the rdme command line tool to compile the comments into a single file that can be uploaded. Comments in Swagger Inline look something like this:

    /*
     * @api [get] /pets
     * description: "Returns all pets from the system that the user has access to"
     * responses:
     *   "200":
     *     description: "A list of pets."
     *     schema:
     *       type: "String"
     */
    
    api.route('/pets', function() {
        /* Pet code 😺 */
    });