DEV: Add missing operationIds to the api docs (PR #14235)

From the openapi spec:

OpenAPI Specification v3.1.0 | Introduction, Definitions, & More

each endpoint needs to have an operationId:

Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.

Running the linter on our openapi.json file with this command:

npx @redocly/openapi-cli lint openapi.json

produced the following warning on all of our endpoints:

Operation object should contain operationId field

This commit resolves these warnings by adding an operationId field to each endpoint.

GitHub

Approving this but I am wondering if there is an easier way to generate a default operation id for these based on the get/post/put method in the spec? I noticed most of these are basically a camel-cased, spaceless variant of the description on the spec e.g.

put 'send download backup email' becomes operationId 'sendDownloadBackupEmail

I am not sure how easy this would be, just something to think about, then no one has to remember to do this, and we could make the description more specific if the operation id for an endpoint needs to be more specific.

Also, are we going to add npx @redocly/openapi-cli lint openapi.json to lefthook.yml at some point?

1 Like

Yea, these really should be generated automatically otherwise it is just busy work. I’ll see if I can make a PR to rswag itself, so that it just generates the operation id for us.

Yep, that is my plan. I just didn’t want to throw it in there while it still was outputting a ton of errors and warnings.