Document REST API endpoints using Springdoc OpenAPI (SZ-12)
rk@tigase.net opened 3 weeks ago

Title: SZ-7 – Document REST endpoints with Springdoc

We need to annotate the main REST controllers with Springdoc OpenAPI annotations so that Swagger UI shows meaningful documentation for internal and external devs.

Applies to:

  • GET /users (filters: username, email, role)
  • GET /projects (filters: ownerId, startAfter, endBefore)
  • GET /issues (filters: status, priority, severity, assigneeId, projectId)

Tasks:

  • Add springdoc-openapi-starter-webmvc-ui to pom.xml
  • Annotate each controller method with @Operation and @Parameter
  • Use @Parameter(hidden = true) for Pageable
  • Ensure enums like IssueStatus, IssuePriority, etc., show up cleanly
  • Use @DateTimeFormat for LocalDate parameters
  • Optionally group endpoints with @Tag

Estimate (rough):

  • Springdoc dependency + config: 0.5h
  • Annotate UserController: 0.5h
  • Annotate ProjectController: 0.5h
  • Annotate IssueController: 0.5h
  • Swagger UI review + testing: 0.5h
  • Enum/date formatting: 0.5–1.0h

Total: 2.5 to 3.5 hours

This is split out from SZ-2 to keep the logic and documentation efforts separate.

  • rk@tigase.net changed state to 'In Progress' 3 weeks ago
    Previous Value Current Value
    Open
    In Progress
issue 1 of 1
Type
New Feature
Priority
Normal
Assignee
Version
none
Sprints
n/a
Customer
n/a
Issue Votes (0)
Watchers (3)
Reference
SZ-12
Please wait...
Page is in error, reload to recover