Skip to content

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
  • Loading branch information
lornajane and ralfhandl authored Sep 8, 2024
1 parent a3d1397 commit 741b7ee
Showing 1 changed file with 23 additions and 12 deletions.
35 changes: 23 additions & 12 deletions proposals/2024-09-01-Tags-Improvement.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ On a personal note, I work for a tool vendor and was proposing these changes int

### Supporting evidence

There are several examples "in the wild" of where a better tags implementation would have helped. Here is a selection of publicly-accessible examples here to illustrate some of the problems this proposal could help with:
There are several examples "in the wild" of where a better tags implementation would have helped. Here is a selection of publicly-accessible examples to illustrate some of the problems this proposal could help with:

- Grouping of tags is a very common use case, almost everyone uses some sort of extra hierarchy to group the tags themselves, which makes sense as our APIs are only getting more complex, something like [`x-tagGroups`](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) is a good example - and there's a [very active open issue on OpenAPI specification itself](https://github.com/OAI/OpenAPI-Specification/issues/1367)
- Various tag-alike additions exist, sometimes called "badges" or similar; I'd include extensions such as [`x-internal`](https://redocly.com/docs/cli/guides/hide-apis/#step-1-add-x-internal-to-the-api-description) as a tag-alike since they could be tags if more than one tag (or tag type) could be applied.
Expand Down Expand Up @@ -102,31 +102,42 @@ This object MAY be extended with [Specification Extensions](#specification-exten

```json
{
"name": "account-updates",
"summary": "Account Updates",
"description": "Account update operations",
"type": "nav"
"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",
"type": "audience"
"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
type: nav
kind: nav

- name: partner
summary: Partner
description: Operations available to the partners network
parent: external
type: audience
kind: audience

- name: external
summary: External
description: Operations available to external consumers
kind: audience
```
---
Expand Down

0 comments on commit 741b7ee

Please sign in to comment.