Swagger Documentation Guide

This guide outlines the standards for configuring and maintaining Swagger API documentation within our codebase. Following these guidelines ensures consistent, clear, and well-organized documentation across all services.

General Rules for Swagger Configuration

1. Using Swagger Annotations:

   • Annotation Priority: Where possible, use Swagger annotations (such as @ApiOperation, @ApiResponses, and @ApiParam) directly in the code to define API metadata, parameter details, and response examples.
   • When to Use: Use annotations for descriptions and examples that are concise, particularly for parameterized details or small response examples.

2. Swagger Customizer:

   • Purpose: Use the customizer to manage complex configurations or examples that would clutter the code if embedded directly.
   • When to Use: If response examples, parameter values, or configurations are extensive or involve nested structures, use a customizer. This keeps annotations manageable and improves code readability.

Documentation Conventions

Metadata Documentation

• Endpoint Descriptions:

  • Use @ApiOperation to describe the functionality of each endpoint clearly. Keep descriptions concise and action-oriented (e.g., "Creates a new contract," "Retrieves a list of contracts").

• Response and Parameter Documentation:

  • Specify all possible responses with @ApiResponses, noting the status code and brief description of each. For example, describe a 201 status as "Successful creation" or a 400 error as "Invalid input."
  • Define parameters with @ApiParam, detailing attributes like required status and brief examples if they enhance clarity.

Examples and Complex Responses

• Using the AbstractSampleObjectFactory:
  • Complex examples and sample responses should be created using factory methods. Developers can find AbstractSampleObjectFactory in the adb-common module. This approach keeps the main code cleaner and makes reusable examples accessible across services.
  • When adding new examples, ensure each factory method provides a clear description of the sample data’s context and a representative value.

Organizing Code with Factory Classes

• Purpose of Factory Classes:
  • Factory classes manage examples for specific response types or request structures, especially when data structures are extensive or nested. This approach enables code reuse and consistency.
• Naming and Documentation:
  • Name each factory class according to the type of object it creates examples for (e.g., TicketSampleObjectFactory for Ticket-related examples).
  • Document each example with a descriptive method name and comments explaining its use (e.g., a creation request example vs. a response example). This gives developers clarity on when and how to use each method.

Summary of Rules

1. Annotations for Simplicity:

   • Use Swagger annotations for direct metadata, parameters, and simple examples.

2. Factory Methods for Complexity:

   • For complex or reusable examples, create and reference factory methods within a dedicated factory class, ensuring code clarity and ease of maintenance.

3. Customizer for Special Configurations:

   • If additional customization or configuration is needed beyond the capabilities of annotations (such as global settings or additional response handling), apply a Swagger customizer to handle these requirements centrally.