-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Additional fields for the tag object #4288
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2687,24 +2687,59 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object | |
|
||
| Field Name | Type | Description | | ||
| ---- | :----: | ---- | | ||
| <a name="tag-name"></a>name | `string` | **REQUIRED**. The name of the tag. | | ||
| <a name="tag-name"></a>name | `string` | **REQUIRED**. The name of the tag. Use this value in the `tags` array of an Operation. | | ||
| <a name="tag-summary"></a>summary | `string` | A short summary of the tag, used for display purposes. | | ||
| <a name="tag-description"></a>description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | ||
| <a name="tag-external-docs"></a>externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this tag. | | ||
| <a name="tag-parent"></a>parent | `string` | The `name` of a tag that this tag is nested under. The named tag MUST exist in the API description, and circular references between parent and child tags MUST NOT be used. | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
This interacts with the following text in 3.1.1:
However, that was written to resolve Operation Object Resolving to the entry document would be the most consistent thing, but not necessarily the most intuitive. On the one hand, making A third option that ends up being more problematic than it seems at first would be to make A fourth option, which would be annoyingly complex, would be to offer both A fifth option would be to define plain name fragments for tags, e.g "tag.{tagname}" so that URI-references would not have to have a numerical index. But we've avoided doing that sort of thing (although JSON Schema's There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm playing around with writing up a There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think we're in agreement here, although perhaps the wording needs work. An OpenAPI description has the tags defined in its entry document, because there's nowhere else to define them. They don't need to be refs, because like the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @lornajane I agree with the decision to merge this, and I'll pick up the subtleties elsewhere since I need to do so for This gets tricky when you have multiple OpenAPI Documents (capital D) in your OAD, each of which can have a list of Tag Objects. Similar problems exist for the Security Requirement and Security Scheme Objects. |
||
| <a name="tag-kind"></a>kind | `string` | A machine-readable string to categorize what sort of tag it is. Any string value can be used; common uses are `nav` for Navigation, `badge` for visible badges, `audience` for APIs used by different groups. A [registry of the most commonly used values](https://spec.openapis.org/registry/tag-kind/) is available. | | ||
lornajane marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
This object MAY be extended with [Specification Extensions](#specification-extensions). | ||
|
||
##### Tag Object Example | ||
|
||
```json | ||
{ | ||
"name": "pet", | ||
"description": "Pets operations" | ||
} | ||
"tags": [ | ||
{ | ||
"name": "account-updates", | ||
"summary": "Account Updates", | ||
"description": "Account update operations", | ||
"kind": "nav" | ||
}, | ||
{ | ||
"name": "partner", | ||
"summary": "Partner", | ||
"description": "Operations available to the partners network", | ||
"parent": "external", | ||
"kind": "audience" | ||
lornajane marked this conversation as resolved.
Show resolved
Hide resolved
|
||
}, | ||
{ | ||
"name": "external", | ||
"summary": "External", | ||
"description": "Operations available to external consumers", | ||
"kind": "audience" | ||
} | ||
] | ||
``` | ||
|
||
```yaml | ||
name: pet | ||
description: Pets operations | ||
tags: | ||
|
||
- name: account-updates | ||
summary: Account Updates | ||
description: Account update operations | ||
kind: nav | ||
|
||
- name: partner | ||
summary: Partner | ||
description: Operations available to the partners network | ||
parent: external | ||
kind: audience | ||
|
||
- name: external | ||
summary: External | ||
description: Operations available to external consumers | ||
kind: audience | ||
``` | ||
|
||
#### Reference Object | ||
|
Uh oh!
There was an error while loading. Please reload this page.