From dac0d3a3c74c188b26fbe60dc508c6d1e97fae6d Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 3 Jan 2025 17:04:30 +0000 Subject: [PATCH 1/3] Add the tag kinds registry and the intial values --- _config.yml | 5 +++++ _includes/tag-kind-entry.md | 17 +++++++++++++++++ registries/_tag-kind/audience.md | 13 +++++++++++++ registries/_tag-kind/badge.md | 13 +++++++++++++ registries/_tag-kind/nav.md | 13 +++++++++++++ registry/index.md | 1 + registry/tag-kind.md | 20 ++++++++++++++++++++ 7 files changed, 82 insertions(+) create mode 100644 _includes/tag-kind-entry.md create mode 100644 registries/_tag-kind/audience.md create mode 100644 registries/_tag-kind/badge.md create mode 100644 registries/_tag-kind/nav.md create mode 100644 registry/tag-kind.md diff --git a/_config.yml b/_config.yml index 0eeaf2fea2..8904b78dd3 100644 --- a/_config.yml +++ b/_config.yml @@ -38,6 +38,11 @@ collections: name: Extension Namespace Registry output: true permalink: /registry/:collection/:title + tag-kind: + slug: tag-kind + name: Tag Kind Registry + output: true + permalink: /registry/:collection/:title exclude: - Gemfile - Gemfile.lock diff --git a/_includes/tag-kind-entry.md b/_includes/tag-kind-entry.md new file mode 100644 index 0000000000..06bec1b63a --- /dev/null +++ b/_includes/tag-kind-entry.md @@ -0,0 +1,17 @@ +# {{ page.collection }} + +## {{ page.slug }} - {{ page.description }} + +{{ include.summary }} + +{% if page.issue %} +### GitHub Issue + +* [#{{ page.issue }}](https://github.com/OAI/OpenAPI-Specification/issues/{{ page.issue }}) +{% endif %} + +{% if page.remarks %} +### Remarks + +{{ page.remarks }} +{% endif %} diff --git a/registries/_tag-kind/audience.md b/registries/_tag-kind/audience.md new file mode 100644 index 0000000000..f01bc32371 --- /dev/null +++ b/registries/_tag-kind/audience.md @@ -0,0 +1,13 @@ +--- +owner: lornajane +issue: +description: "Tags with `kind: audience` indicate the intended audience for an operation." +layout: default +--- + +{% capture summary %} +Tags with `kind: audience` indicate the intended audience for an operation. +Common uses might be to tag internal, admin-level, or partner endpoints. +{% endcapture %} + +{% include tag-kind-entry.md summary=summary %} diff --git a/registries/_tag-kind/badge.md b/registries/_tag-kind/badge.md new file mode 100644 index 0000000000..74ebb867ba --- /dev/null +++ b/registries/_tag-kind/badge.md @@ -0,0 +1,13 @@ +--- +owner: lornajane +issue: +description: " Tags with `kind: badge` are applied as visible badges in documentation." +layout: default +--- + +{% capture summary %} +Tags with `kind: badge` are applied as visible badges in documentation. +It is expected that an operation might have many badges. +{% endcapture %} + +{% include tag-kind-entry.md summary=summary %} diff --git a/registries/_tag-kind/nav.md b/registries/_tag-kind/nav.md new file mode 100644 index 0000000000..b5d25963b9 --- /dev/null +++ b/registries/_tag-kind/nav.md @@ -0,0 +1,13 @@ +--- +owner: lornajane +issue: +description: "Tags with `kind: nav` are used in documentation to group operations into sections" +layout: default +--- + +{% capture summary %} +Tags with `kind: nav` are used in documentation to group operations into sections. +In most cases, an operation only has one tag of this tag so it belongs in one section. +{% endcapture %} + +{% include tag-kind-entry.md summary=summary %} diff --git a/registry/index.md b/registry/index.md index 73632ab5c4..6bda6ed1e6 100644 --- a/registry/index.md +++ b/registry/index.md @@ -8,6 +8,7 @@ children: - title: Draft Features Registry - title: Format Registry - title: Namespace Registry +- title: Tag Kinds Registry has_toc: false --- diff --git a/registry/tag-kind.md b/registry/tag-kind.md new file mode 100644 index 0000000000..d591473553 --- /dev/null +++ b/registry/tag-kind.md @@ -0,0 +1,20 @@ +--- +title: Tag Kinds Registry +layout: default +permalink: /registry/tag-kind/index.html +parent: Registry +--- + +# Tag Kinds Registry + +## Contributing + +Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) or [Issue](https://github.com/OAI/OpenAPI-Specification/issues) to contribute or discuss a registry value. + +## Values + +|Value|Description +|---|---|---| +{% for value in site.tag-kind %}| {{ value.slug }} | {{ value.description }} | +{% endfor %} + From 1b10bbc95f157cb3bc940e0516c614fbecae46c1 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Fri, 3 Jan 2025 17:08:31 +0000 Subject: [PATCH 2/3] Add a note about availability --- registry/tag-kind.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/registry/tag-kind.md b/registry/tag-kind.md index d591473553..3c45eb1c69 100644 --- a/registry/tag-kind.md +++ b/registry/tag-kind.md @@ -7,6 +7,10 @@ parent: Registry # Tag Kinds Registry +## Unreleased feature + +The `kind` addition to OpenAPI tags is planned for release in OpenAPI 3.2, so support for the values here should not be expected until tools officially support the 3.2 version. + ## Contributing Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) or [Issue](https://github.com/OAI/OpenAPI-Specification/issues) to contribute or discuss a registry value. From d09051aefdc2e9fc4457250982c0ba576a1e87a7 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Thu, 9 Jan 2025 17:12:39 +0000 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Mike Kistler --- registries/_tag-kind/nav.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/registries/_tag-kind/nav.md b/registries/_tag-kind/nav.md index b5d25963b9..917fd440a8 100644 --- a/registries/_tag-kind/nav.md +++ b/registries/_tag-kind/nav.md @@ -7,7 +7,7 @@ layout: default {% capture summary %} Tags with `kind: nav` are used in documentation to group operations into sections. -In most cases, an operation only has one tag of this tag so it belongs in one section. +In most cases, an operation only has one tag of this type so it belongs in one section. {% endcapture %} {% include tag-kind-entry.md summary=summary %}