Back to all reviewers

Prevent API documentation duplication

appwrite/appwrite
Based on 2 comments
Json

When maintaining API specification files (like OpenAPI or Swagger), ensure consistency and avoid duplication that can confuse documentation generators and API consumers:

Documentation Json

Reviewer Prompt

When maintaining API specification files (like OpenAPI or Swagger), ensure consistency and avoid duplication that can confuse documentation generators and API consumers:

  1. Eliminate duplicate service definitions - Remove or merge tags that represent the same service with different names (e.g., “projects” and “project”).

  2. Standardize naming conventions - Use consistent casing and plural/singular forms for similar entities across all documentation.

  3. Maintain consistent style - Ensure all descriptions:

    • End with proper punctuation (typically periods)
    • Use correct grammar
    • Maintain consistent tone and formatting

Example:

// BAD: Duplicate tags with inconsistent descriptions
"tags": [
  {
    "name": "projects",
    "description": "The Project service allows you to manage all the projects in your Appwrite server."
  },
  {
    "name": "project",
    "description": "The Project service allows you to manage all the projects in your Appwrite server."
  }
]

// GOOD: Single, well-defined tag
"tags": [
  {
    "name": "projects",
    "description": "The Projects service allows you to manage all the projects in your Appwrite server."
  }
]

This consistency helps maintain clear documentation and prevents confusion in generated code or documentation.

2
Comments Analyzed
Json
Primary Language
Documentation
Category

Source Discussions