From f822af73874e9b8ff61e5b98c1f37904b1471934 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 3 Jan 2025 16:03:30 +0000 Subject: [PATCH 1/4] Add more fields to the tag object, from the proposal --- src/oas.md | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/src/oas.md b/src/oas.md index 2ffed2bc76..80f4719b98 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2687,9 +2687,12 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object | Field Name | Type | Description | | ---- | :----: | ---- | -| name | `string` | **REQUIRED**. The name of the tag. | +| name | `string` | **REQUIRED**. The name of the tag. Use this value in the `tags` array of an Operation. | +| summary | `string` | A short summary of the tag, used for display purposes. | | description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this tag. | +| parent | `string` | The `name` of a tag that this tags is nested under. The named tag MUST exist in the API description, and circular references between parent and child tags MUST NOT be used. | +| kind | `string` | A machine-readable string to categorize what sort of tag it is. Common uses are `nav` for Navigation, `badge` for badges, `internal` for internal APIs, but any string value can be used. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -2697,14 +2700,42 @@ This object MAY be extended with [Specification Extensions](#specification-exten ```json { - "name": "pet", - "description": "Pets operations" + "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" } ``` ```yaml -name: pet -description: Pets operations +- 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 From d3d86330a0a97d536ac5ac8692c4a772390bfbcb Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 3 Jan 2025 17:41:01 +0000 Subject: [PATCH 2/4] Better formatting of examples --- src/oas.md | 72 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/src/oas.md b/src/oas.md index 80f4719b98..94f8aa039a 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2699,43 +2699,47 @@ This object MAY be extended with [Specification Extensions](#specification-exten ##### Tag Object Example ```json -{ - "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" -} +"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" + } +] ``` ```yaml -- 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 +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 From a055eca66fd83b8b8ef3098f2a101f166e7d501d Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 10 Jan 2025 12:19:21 +0000 Subject: [PATCH 3/4] Improve tag kind wording and link registry --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 94f8aa039a..b33ce9cd32 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2692,7 +2692,7 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object | description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this tag. | | parent | `string` | The `name` of a tag that this tags is nested under. The named tag MUST exist in the API description, and circular references between parent and child tags MUST NOT be used. | -| kind | `string` | A machine-readable string to categorize what sort of tag it is. Common uses are `nav` for Navigation, `badge` for badges, `internal` for internal APIs, but any string value can be used. | +| 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. | This object MAY be extended with [Specification Extensions](#specification-extensions). From 581391aa7582ae3c0afc93aff9dda3687835eb70 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 10 Jan 2025 16:41:10 +0100 Subject: [PATCH 4/4] Typo Co-authored-by: Mike Kistler --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index b33ce9cd32..3999e66d2f 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2691,7 +2691,7 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object | summary | `string` | A short summary of the tag, used for display purposes. | | description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this tag. | -| parent | `string` | The `name` of a tag that this tags is nested under. The named tag MUST exist in the API description, and circular references between parent and child tags MUST NOT be used. | +| 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. | | 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. | This object MAY be extended with [Specification Extensions](#specification-extensions).