Introduce Summary Field on Tag Object #2843
Description
Suggested Enhancement
Add a field called summary (or, alternatively, label or title) to the Tag Object.
This optional field would be used as the "human readable" representation of the tag name, in case it's provided.
Problem
When tags are used for grouping endpoints (documentation generators often use tags for this), the lack of a summary (or label) field causes problems.
For example, say that you have these grouped endpoints:
- Manage Users
- Create a user (POST)
- Read a user (GET)
- Manage Articles
- Create an article (POST)
- Read an article (GET)
- Remove an article (DELETE)
You'd have to use the following tag data:
# CODE TODAY
# root
tags:
- name: User Management
description: Manage users via our API.
- name: Article Management
description: Manage articles via our API.
# on each endpoint
operationId: abc
tags: [User Management]
summary: Create a userIn this case you'd rather set tags to [users] on each operation/endpoint, and use a global summary field for the tag, with the value User Management.
# DESIRED CODE
# root
tags:
- name: users
summary: User Management
description: Manage users via our API.
- name: articles
summary: Article Management
description: Manage articles via our API.
# on each endpoint
operationId: abc
tags: [users]
summary: Create a userOpen Questions
- What should the field be named? (summary, label, title, or something else?)
For reference, here are some Swagger documentation on this topic:
https://swagger.io/docs/specification/grouping-operations-with-tags/