Skip to content

Guidelines for operation tags #80

@rartych

Description

@rartych

Problem description
Current API DG says that for each HTTP method (i.e operation) definition should include:

Tag list to classify methods.

Expected action
More detailed guidelines on usage and style of operation tags:

  • Definition of tags in a top-level tags element
  • Adding a tag to each operation

Additional context

tags element is not required by OAS:

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#fixed-fields

A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.

The need for guidelines was indicated in the discussion in camaraproject/QualityOnDemand#227

Explanation of tags in blog post.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions