Skip to content

Commit 315b2dc

Browse files
feat: add docs for the async api
1 parent 4019a7a commit 315b2dc

File tree

1 file changed

+92
-0
lines changed

1 file changed

+92
-0
lines changed
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# tags-duplicated-names
2+
3+
Ensures that tag names in the `tags` array are unique.
4+
This rule prevents duplication of tag names which could lead to inconsistent API documentation.
5+
6+
| AsyncAPI | Compatibility |
7+
| -------- | ------------- |
8+
| 2.6 ||
9+
| 3.0 ||
10+
11+
## API design principles
12+
13+
Tags are used to group operations in AsyncAPI specifications. Each tag should be unique to clearly categorize operations.
14+
Having duplicate tags can cause confusion in documentation rendering tools, makes the specification harder to maintain,
15+
and may lead to operations being grouped incorrectly.
16+
17+
## Configuration
18+
19+
| Option | Type | Description |
20+
| ---------- | ------- | ----------------------------------------------------------------------------------- |
21+
| severity | string | Possible values: `off`, `warn`, `error`. Default `warn`. |
22+
| ignoreCase | boolean | Possible values: `true`, `false`. Default `false` (in `recommended` configuration). |
23+
24+
An example configuration:
25+
26+
```yaml
27+
rules:
28+
tags-duplicated-names: error
29+
```
30+
31+
With ignoring case:
32+
33+
```yaml
34+
rules:
35+
tags-duplicated-names:
36+
severity: error
37+
ignoreCase: true
38+
```
39+
40+
## Examples
41+
42+
Given this configuration:
43+
44+
```yaml
45+
rules:
46+
tags-duplicated-names: error
47+
```
48+
49+
Example of **incorrect** tags:
50+
51+
```yaml Bad example
52+
tags:
53+
- name: pet
54+
description: Everything about your Pets
55+
- name: store
56+
description: Access to Petstore orders
57+
- name: store
58+
description: Duplicated store tag
59+
```
60+
61+
Example of **correct** tags:
62+
63+
```yaml Good example
64+
tags:
65+
- name: pet
66+
description: Everything about your Pets
67+
- name: store
68+
description: Access to Petstore orders
69+
- name: user
70+
description: Operations about user
71+
```
72+
73+
With **ignoreCase: true**, this would also be incorrect:
74+
75+
```yaml
76+
tags:
77+
- name: pet
78+
description: Everything about your Pets
79+
- name: store
80+
description: Access to Petstore orders
81+
- name: Store
82+
description: Case-sensitive duplicate
83+
```
84+
85+
## Related rules
86+
87+
- [tag-description](./tag-description.md)
88+
89+
## Resources
90+
91+
- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/tags-duplicated-names.ts)
92+
- [Tags docs](https://redocly.com/docs/openapi-visual-reference/tags/)

0 commit comments

Comments
 (0)