apirestful/SWAGGER.md

Swagger/OpenAPI Quick Reference

Access URLs

Resource	URL	Description
Swagger UI	http://localhost:8080/swagger-ui.html	Interactive API documentation
OpenAPI JSON	http://localhost:8080/v3/api-docs	OpenAPI 3.0 specification in JSON
OpenAPI YAML	http://localhost:8080/v3/api-docs.yaml	OpenAPI 3.0 specification in YAML

Swagger UI Features

1. Try It Out

Click "Try it out" on any endpoint to test it directly from the browser.

2. Model Schemas

View detailed schemas for:

• CustomerDTO (response)
• CustomerRequestDTO (request)

3. Response Codes

Each endpoint shows:

• 200: Success
• 201: Created
• 204: No Content
• 400: Bad Request (validation errors)
• 404: Not Found
• 409: Conflict (duplicate email)

4. Examples

Pre-filled example values for easy testing.

API Endpoints in Swagger

Customer Management Tag

GET /api/customers

Summary: Get all customers
Description: Retrieves a list of all customers in the system asynchronously
Response: 200 - Array of CustomerDTO

GET /api/customers/{id}

Summary: Get customer by ID
Description: Retrieves a specific customer by their unique identifier
Parameters:

• id (path, required): ID of the customer to retrieve Responses:
• 200: Customer found
• 404: Customer not found

POST /api/customers

Summary: Create a new customer
Description: Creates a new customer with the provided information. Email must be unique.
Request Body: CustomerRequestDTO Responses:

• 201: Customer created successfully
• 400: Invalid input data
• 409: Email already exists

PUT /api/customers/{id}

Summary: Update a customer
Description: Updates an existing customer's information by ID
Parameters:

• id (path, required): ID of the customer to update Request Body: CustomerRequestDTO Responses:
• 200: Customer updated successfully
• 400: Invalid input data
• 404: Customer not found
• 409: Email already exists

DELETE /api/customers/{id}

Summary: Delete a customer
Description: Deletes a customer from the system by their ID
Parameters:

• id (path, required): ID of the customer to delete Responses:
• 204: Customer deleted successfully
• 404: Customer not found

Annotations Used

Controller Level

@Tag(name = "Customer Management", description = "APIs for managing customer data with async operations")

Endpoint Level

@Operation(
    summary = "Get all customers",
    description = "Retrieves a list of all customers..."
)
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Successfully retrieved customers",
        content = @Content(mediaType = "application/json",
            schema = @Schema(implementation = CustomerDTO.class)))
})

DTO Level

@Schema(description = "Customer response data")
public class CustomerDTO {
    @Schema(description = "Unique identifier of the customer", example = "1")
    private Long id;
    
    @Schema(description = "First name of the customer", example = "John")
    private String firstName;
    // ...
}

Configuration

OpenAPI Bean Configuration

Located in: src/main/java/com/manalejandro/apirestful/config/OpenAPIConfig.java

Features:

• Custom API title and version
• Contact information
• License information
• Server URL configuration

Security Configuration

Swagger endpoints are allowed without authentication:

.requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/swagger-ui.html").permitAll()

Application Properties

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha

Testing with Swagger UI

1. Open http://localhost:8080/swagger-ui.html
2. Expand "Customer Management" section
3. Click on any endpoint (e.g., POST /api/customers)
4. Click "Try it out"
5. Edit the request body if needed
6. Click "Execute"
7. View the response below

Tips

• Use the "Authorize" button if you add authentication later
• Download the OpenAPI spec for use with other tools (Postman, Insomnia)
• The spec can be imported into API testing tools
• All async operations return CompletableFuture but are transparent to the API consumer