Naming guideline for openapi tags

[jpraet]

Rule 34: https://www.belgif.be/specification/rest/api-guide/#openapi

When an API has many operations, use tags to group them together. This will make the visual representation (SwaggerUI) more readable.

But it does not talk about how to name tags.

• https://petstore3.swagger.io/ has "lowercase" tags like "pet", "store", "user"
• but plenty real world examples seem to use "Capitalized Words":
  • https://api.twitter.com/2/openapi.json
  • https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#openapi-tags
  • https://github.com/belgif/openapi-common/blob/1af5851d093ec6142052e9b5c876194d6914c615/src/main/openapi/common/v1/common-v1.yaml#L10

[jpraet]

https://github.com/belgif/rest-guide-example/blob/main/src/main/openapi/openapi.yaml uses UpperCamelCase (no spaces) e.g. "ReferenceData"

[pvdbosch]

For readability, Capitalized Words look best to me.

I'd also recommend to list each tag in the "tags" root level openapi property. This isn't a requirement for OpenAPI, but it allows a styleguide validator to detect typos.

[pvdbosch]

SwaggerUI displays an operation multiple times for each of its tags, which is quite confusing. Maybe we should limit to max one tag on each operation?

[pvdbosch]

Conclusions REST WG:

• Capitalized word group (you may choose to capitalize each word, or only the first one); not a technical UpperCamelCase wording, underscores etc, more stylized like titles
• one tag per operation ("SHOULD"), validator supports to ignore it using x-ignore-rules
• tags set on operations should be predefined under "tags" (root level property of OpenAPI doc)

I'll create a PR and create ticket to add rule to validator

[pvdbosch]

PR #171 ready for review

[pvdbosch]

PR has been merged and will be published next release.