server-description-exists
Overview
This rule belongs to the openapi-v3-docsgen-linting ruleset and states that:
The description property in the Server object provides a description of the server. It should not be missing or empty. The description helps API users understand the purpose and context of the server. Providing a description is an essential part of API documentation and helps to communicate the server's functionality to developers. A missing or empty description property can lead to confusion and ambiguity in the API documentation, making it difficult for developers to understand the API's intended purpose.
| Property | Value |
|---|---|
| Enabled | Yes |
| Maximum Severity | Information |
| Message | Missing or empty description property for server object. |
| Code | OPENAPI3DOCSGEN_L151 |
| Type | Linting |
| Rule System | Semantic |
| Broad Category | OpenAPI Servers |
| Products Impacted | Developer Experience Portal |
| Tags | documentation generation documentation docs openapi3 openapi semantic linting apimatic server description |
Suggested Fixes
- Add a non-empty description property to each server object, providing a brief description of the server's purpose, location, or other relevant details.
- Ensure that the description property accurately reflects the intended use of the server and is clear and concise.