OpenAPI / Swagger

OpenAPI Annotations

@RestController
@RequestMapping("/api/products")
@Tag(name = "Products", description = "Product management APIs")
public class ProductController {

    @Operation(summary = "Get product by ID",
               description = "Retrieves a single product by its unique identifier")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Product found",
            content = @Content(schema = @Schema(implementation = Product.class))),
        @ApiResponse(responseCode = "404", description = "Product not found")
    })
    @GetMapping("/{id}")
    public ResponseEntity<Product> getProduct(
            @Parameter(description = "Product ID") @PathVariable Long id) {
        return ResponseEntity.ok(productService.getById(id));
    }

    @Operation(summary = "Create a new product")
    @PostMapping
    public ResponseEntity<Product> createProduct(
            @Valid @RequestBody CreateProductRequest request) {
        Product product = productService.create(request);
        return ResponseEntity.status(201).body(product);
    }
}

OpenAPI Structure

openapi: 3.0.0
info:
  title: Product API
  version: 1.0.0
paths:
  /products:
    get:
      summary: List products
      parameters:
        - name: category
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number

Swagger UI Features

• Try it out — Execute requests from browser
• Schema viewer — Visualize data models
• Authentication — Test with auth tokens
• Download — Export OpenAPI spec

Design Principles

• Use nouns, not verbs
• Plural resource names
• Consistent naming conventions
• Proper HTTP status codes

Versioning

• URI versioning (/v1/resource)
• Header versioning
• Deprecation policy

Documentation

• OpenAPI/Swagger specs
• Request/Response examples
• Error code documentation
• Rate limit documentation

Key Points

• Understanding OpenAPI and Swagger is essential for production systems
• Always consider scalability and maintainability
• Test thoroughly before deploying to production
• Monitor performance and set up alerting

Common Patterns

1. Validation: Always validate input at the boundary
2. Error Handling: Use structured error responses
3. Logging: Log key events for debugging
4. Testing: Unit, integration, and load tests
5. Documentation: Keep docs updated with code changes