Introduce Summary Field on Tag Object

[sandstrom]

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 user

In 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 user

Open 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/

[sandstrom]

@MikeRalphson @webron @darrelmiller happy to hear your thoughts! Maybe I've missed something obvious, that makes this a bad idea.

[basilfx]

I would also be interested in this enhancement as well.

I currently consider tags as machine-readable because operations are machine-readable (and the referenced documentation page has the title "Grouping Operations With Tags"). For UI (generation), having something like a summary/label/title would help.

[lornajane]

I've seen x-displayName used with tags in a few places. Also whether we add this for OpenAPI 3.x or not, I've also got a proposal open for richer tags in the next major release of OpenAPI - feel free to engage with that discussion also https://github.com/OAI/sig-moonwalk/discussions/67

[lornajane]

Update: I wrote up a proposal to introduce the summary field for tags: https://github.com/OAI/OpenAPI-Specification/pull/4063 - if you are following this issue, please go and check it does what you had in mind?

[lornajane]

Fixed in #4288, which is now merged.

[sandstrom]

@lornajane Great! 🎉

[sandstrom]

@erunion @mjcuva Sorry for the direct ping, but this (this issue and the linked PR https://github.com/OAI/OpenAPI-Specification/pull/4288) should help fix an annoyance in your API.

Before this fix we need to first create your categories in UI and then obtain the values to set in open api spec files. See our internal comments about this complexity below.

So basically, you should start supporting this, so we wouldn't need a two-step process to create categories.

Let me know if I should elaborate!