Re-syncing Your OpenAPI Document

API Definition IDs

Once you've uploaded an OpenAPI file to ReadMe, you'll see the following in the API Reference settings of your dashboard (the red outline is where you'll find your API definition ID):

Alternatively, you can obtain the API definition ID by running the following rdme CLI command on your local machine:

rdme openapi [url-or-local-path-to-file]

Once you follow the prompts and upload your OpenAPI definition, you'll receive a confirmation message that looks something like this:

You've successfully updated an OpenAPI file on your ReadMe project!

        http://dash.readme.com/project/{your_project}/v1.0/refs/pet

To update your OpenAPI definition, run the following:

        rdme openapi [url-or-local-path-to-file] --key=<key> --id=API_DEFINITION_ID

The API_DEFINITION_ID is the API definition ID within ReadMe.

Operation IDs

On re-sync of your OpenAPI file, pages are merged with existing pages if they are present. We use operationId of the Operation Object to determine what pages are considered to be the same.

If on re-sync there is a new operationId, then a new page is created. If on re-sync an operationId is removed, then the page is removed.

If you do not have an operationId, we create one for you using the following algorithm.

With an endpoint like this:

{
  "/pet": {
    "post": {
    }
  }
}

We take the path /pet, remove any non-alphanumeric characters, lowercase it and concatenate it onto the end of the method. So the above would become post_pet.

❗️

We recommend you always provide anoperationId for each of your endpoints to reduce the risk of data loss associated with us creating a unique ID for you.