How de0811/spring-docs works
Main Components
• Backend Application: Representing the core of the project, the DocsApplication.java (located in src/main/java/com/sdm/docs) acts as the primary entry point.
• API Controllers: Include components such as SwaggerTestController.java within the controller package. These manage the API endpoints that are both tested (to produce documentation) and later used for testing via Swagger UI.
• Security Configuration: The SecurityConfig.java component is used to set up CORS and any other security measures.
• API Documentation Generation Module: This aspect comes into play through the test code (e.g., DocsApplicationTests, SwaggerControllerSupportTest) and the Gradle build script (build.gradle). When the “openapi3” Gradle task runs, it produces the openapi3.json file in the build/api-spec directory.
• External Swagger UI Service: The system uses Docker (or docker-compose) to run a Swagger UI container that loads the generated openapi3.json file, allowing interactive API testing.
Establish Relationships and Interactions
• The Backend Application (DocsApplication) exposes various REST endpoints managed by the controller (SwaggerTestController).
• During testing, the restdocs-api-spec functionality (through Gradle tasks) triggers test cases that produce API documentation (openapi3.json). The tests simulate API calls to generate accurate documentation.
• The SecurityConfig component ensures proper CORS and security settings for interactions between the Swagger UI and the backend API.
Architectural Patterns and Key Technologies
• Modular Separation: Although it’s a monolithic application, note the clear separation between configuration, controllers, DTOs, and tests.
• Build & Deployment Practices: Gradle is used for building and testing; Docker/Docker Compose is used for deploying the Swagger UI environment.
• Technology Stack: Spring Boot for the backend, Spring Rest Docs combined with Swagger UI, and Gradle for builds. Additionally, Docker plays a role in running the Swagger UI container.