REST API Design & Swagger
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/org/example/coding_convention/config/SwaggerConfig.java
- src/main/java/org/example/coding_convention/common/model/BaseResponse.java
- src/main/java/org/example/coding_convention/project/controller/ProjectController.java
- src/main/java/org/example/coding_convention/user/controller/UserController.java
- src/main/java/org/example/coding_convention/chat/controller/ChatController.java
- src/main/java/org/example/coding_convention/config/filter/JwtAuthFilter.java
- src/main/java/org/example/coding_convention/project/model/ProjectDto.java
- src/main/java/org/example/coding_convention/file/model/FilesDto.java
Introduction
The PhanesEditor backend employs a structured REST API design combined with OpenAPI 3.0 (Swagger) for comprehensive documentation and testing. The API is designed to support real-time collaboration features, including project management, user authentication, and chat functionalities. By utilizing Swagger, the project provides a centralized interface for developers to interact with and understand the available endpoints, data models, and security requirements.
The architecture emphasizes consistency through a unified response format (BaseResponse) and secures endpoints using JWT-based "Bearer" authentication. This ensures that all client-server interactions are predictable and protected based on user permissions within specific projects.
Swagger Configuration & Security
The API documentation is managed via SwaggerConfig, which defines the global metadata and security schemes for the "Phanes API".
OpenAPI Definition
The project uses the @OpenAPIDefinition annotation to set the API title as "Phanes API" (version v1) and enforces a global security requirement named bearerAuth. This ensures that most endpoints require a valid JSON Web Token (JWT) for access.
Security Scheme
The security is implemented using an HTTP Bearer scheme with a JWT format. This allows developers to authorize requests within the Swagger UI by providing a token.
Standardized Response Structure
All REST endpoints return a consistent JSON structure wrapped in the BaseResponse<T> class. This allows the client to reliably parse success status, descriptive messages, and the actual data payload.
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the request was processed successfully. |
message | String | A human-readable response message (e.g., "요청에 성공했습니다."). |
results | T (Generic) | The actual data returned by the API (User info, Project list, etc.). |
Sources: src/main/java/org/example/coding_convention/common/model/BaseResponse.java:13-20
Controller Implementations
The API is logically divided into controllers focused on specific domains. Each controller uses Swagger annotations like @Tag and @Operation to describe its purpose and specific endpoints.
Project Management (ProjectController)
Handles the lifecycle and retrieval of collaboration projects. It integrates with ProjectDto to define the input and output structures for project creation, listing, and detailed reading.
| Endpoint | Method | Description |
|---|---|---|
/project/create | POST | Creates a new project with name, description, and language. |
/project/list | GET | Retrieves projects the authenticated user is participating in. |
/project/read | GET | Fetches full project details including members, files, and chats. |
/project/search | GET | Supports paginated search by name, email, or language. |
Sources: src/main/java/org/example/coding_convention/project/controller/ProjectController.java:23-74, src/main/java/org/example/coding_convention/project/model/ProjectDto.java:23-40
User & Authentication (UserController)
Manages user registration, profile retrieval, and authentication state.
Chat & Collaboration (ChatController)
Facilitates the storage of persistent chat messages within a project context.
- Endpoint:
POST /chat/register - Request Body:
ChatsDto.ChatRegister(containsprojectIdandmessage). - Logic: Uses
@AuthenticationPrincipalto automatically associate the chat with the logged-in user.
Sources: src/main/java/org/example/coding_convention/chat/controller/ChatController.java:18-30
Data Transfer Objects (DTO) with Schema Annotations
DTOs are annotated with @Schema to provide clear documentation of field requirements and example values within the Swagger UI.
Example: Project Registration DTO
@Schema(description = "프로젝트 저장용 DTO")
public static class ProjectReq {
@Schema(description = "프로젝트 이름", example = "자바 프로젝트")
private String projectName;
@Schema(description = "프로젝트 설명", example = "자바로 알고리즘을 구현해 보자")
private String description;
@Schema(description = "프로젝트 대표 사용 언어", example = "JAVA")
private String language;
}
Sources: src/main/java/org/example/coding_convention/project/model/ProjectDto.java:19-35
Example: File Registration DTO
Includes validation patterns to ensure file names do not contain illegal characters.
- Pattern:
^[a-zA-Z0-9._-]+$ - Schema Example:
show.txt
Sources: src/main/java/org/example/coding_convention/file/model/FilesDto.java:71-82
API Security Interception
The JwtAuthFilter acts as a gateway for all REST requests, ensuring that Swagger resources are accessible while other endpoints are strictly protected.
Summary
The REST API Design & Swagger implementation in PhanesEditor-BE provides a robust, self-documenting interface for the collaborative editor. By leveraging OpenAPI 3.0 annotations and a centralized BaseResponse model, the project ensures that the frontend and external developers have a clear contract for data exchange. Security is seamlessly integrated through a JWT filter that respects Swagger's documentation paths while enforcing "Bearer" authentication on all business-critical endpoints.