Category: Semantic Analysis
Description
Operations within a tag should be semantically cohesive. This rule detects operations that don't fit with others in the same tag and suggests better organization.
What It Checks
This rule analyzes tag organization using semantic similarity:
- Groups operations by their assigned tags
- Computes semantic similarity between operations in the same tag
- Identifies outliers that deviate significantly from the tag's theme
- Suggests alternative tags when a better fit exists
Why It Matters
Well-organized tags improve:
- API Navigation: Easier to find related endpoints
- Documentation Quality: Logical grouping aids understanding
- Discoverability: Related operations are together
- Maintainability: Clear boundaries between API domains
Examples
Good
tags:
- name: Users
- name: Orders
paths:
/users:
get:
tags: [Users]
summary: List all users
/users/{id}:
get:
tags: [Users]
summary: Get user by ID
/orders:
get:
tags: [Orders]
summary: List all orders
Bad
tags:
- name: Users
- name: Orders
paths:
/users:
get:
tags: [Users]
summary: List all users
/orders:
get:
tags: [Users] # Should be in Orders tag
summary: List all orders
/users/{id}:
get:
tags: [Users]
summary: Get user by ID
Exceptions
- APIs with intentionally broad tags
- Cross-cutting operations that legitimately span domains
- Tags used for access control rather than organization
Configuration
This rule supports configuration options:
- std_devs: Number of standard deviations below mean to flag as outlier (default: 1.5)
- Options: 1.0, 1.5, 2.0, 2.5, or custom value
- min_threshold: Absolute minimum similarity threshold (default: 0.6)
- Options: 0.5, 0.6, 0.7, 0.8, or custom value
Related Rules
- Rule 77: Semantic Consistency - Naming consistency
- Rule 80: Schema Field Naming - Field naming quality