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.