The root-level tags object should list all the desired tags (groups) in your API. Then, in each path object, under Paths, list the tag under which you want to group that path. I apply tags to the following specifications and extend my OpenAPI tagging approach to be more on a universal way to organize all my resources: I like my OpenAPI tags. Honestly, I like tags in general. Almost every API resource I design has some sort of markup layer. I have a centralized markup vocabulary that I use in my JSON, OpenAPI, and AsyncAPI schema to group, organize, filter, publish, and manage my catalog of API and schema resources. To submit content with form URL encoding on RFC1866, the following definition can be used: Assuming the following paths, the concrete definition /pets/mine is first mapped when used: The xml property allows additional definitions when translating the JSON definition to XML. The XML object contains additional information about the available options. The OpenAPI specification allows you to combine and extend model definitions using the allOf property of the JSON schema, providing the composition of the model. allOf uses an array of object definitions that are independently validated, but together form a single object. List of tags used by the specification with additional metadata.
The order of the tags can be used by analysis tools to reflect their order. It is not necessary to declare all tags used by the Operation object. Tags that are not declared CAN be arranged randomly or according to tool logic. Each tag name in the list MUST be unique. An OpenAPI document MAY, at the user`s discretion, consist of a single document or be divided into several interconnected parts. In the latter case, $ref fields in the specification MUST be used to refer to these parts, as specified in the JSON schema definitions. For example, when changing its openapi property to 3.1.0, a valid OpenAPI 3.0.2 document MUST be a valid OpenAPI 3.1.0 document that semantically matches the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI specification MUST be written to ensure this form of backward compatibility. In scenarios where the discriminator field value does not match the schema name or implicit mapping is not possible, an optional mapping definition MAY be used: Tags are an important dimension of API discoverability when it comes to my API definitions. They provide rich metadata that I can use to understand my API framework.
Without it, the quality of my API definitions tends to drop. By developing the markup schema and investing in tools that help me understand the API definitions I depend on, I can push the boundaries of the tag and make it the core of managing my API definitions. We only have one tag, but you can have as many as you want (if you have a lot of endpoints, it would make sense to create multiple tags to group them together). You can list the name and a description for each tag. The description appears as a subtitle for the tag name in the Swagger user interface. Although composition provides model extensibility, it does not imply a hierarchy between models. To support polymorphism, the OpenAPI specification adds the discriminator field. When used, the discriminator is the name of the property that decides which schema definition verifies the structure of the model. Therefore, the discriminant field MUST be a required field.
There are two ways to define the value of a discriminator for an inheriting entity. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to build servers and clients in different programming languages, testing tools, and many other use cases. The tag object for the OpenAPI specification is fairly simple and allows you to add tags for an entire API contract and apply them to each API method. Tools such as API documentation use these tags to group your API resources so that you can divide your resources into logically limited contexts.