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..917fd440a8 --- /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 type 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..3c45eb1c69 --- /dev/null +++ b/registry/tag-kind.md @@ -0,0 +1,24 @@ +--- +title: Tag Kinds Registry +layout: default +permalink: /registry/tag-kind/index.html +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. + +## Values + +|Value|Description +|---|---|---| +{% for value in site.tag-kind %}| {{ value.slug }} | {{ value.description }} | +{% endfor %} +