Promoting the API I Built - A Guide to Spring REST Docs

Kurly redeveloping its gift-sending system project switched its existing Wiki-based API documentation to a Spring REST Docs based approach. Initially, a choice had to be made between Swagger (Springdoc) and Spring REST Docs, but the team adopted Spring REST Docs to avoid Swagger annotations infiltrating production code and to enforce test writing in order to secure service stability.

Spring REST Docs works by running test code to generate Asciidoc snippets, which are then rendered into HTML documentation. Since no documentation is generated without tests, it has the advantage of allowing immediate detection of missing fields or response values when the API changes. On the other hand, static HTML documentation alone had the limitation of making it difficult for planners or operators to directly test the API.

Securing Testing Convenience Through Swagger UI Integration

To overcome this limitation, the team introduced an approach using the ePages-de/restdocs-api-spec library to generate OpenAPI Specification (OAS) documents in JSON or YAML format. By sharing the existing test code to generate OAS documents and linking them to Swagger UI, it became possible to directly test API requests and responses within the documentation.

• Included the generated openapi3.yaml file as a static resource via build.gradle configuration
• Configured Swagger UI access paths and applied CORS and CSRF disabling (development environment only)
• Enabled API testing using the generated YAML file with external tools such as Postman

This approach became a solution that minimizes infiltration of production code while simultaneously providing reliable, test-based documentation and a visually convenient testing interface.