OpenAPI와 Swagger로 REST API 문서화

An API is only useful if consumers understand it. Good documentation describes endpoints, parameters, request bodies, and responses so other teams can integrate without guessing.

OpenAPI is a vendor-neutral specification for describing REST APIs in a machine-readable format. Tools can read it to generate docs, client SDKs, and test suites.

The springdoc-openapi library scans your controllers and produces an OpenAPI document automatically. Just add the dependency and it works out of the box.

Once added, visit /swagger-ui.html to get an interactive page where you can browse endpoints and try them live from the browser.

The raw OpenAPI document is served at /v3/api-docs. This JSON is what other tools consume to generate clients or import into platforms like Postman.

Use @Operation to add a summary and description to an endpoint, making the generated docs clearer for consumers.

The @ApiResponses annotation lets you list possible status codes and their meanings so callers know what to expect.

Annotate DTO fields with @Schema to give examples and descriptions. This makes the model section of your docs self-explanatory.

Provide a title, version, and contact info with an OpenAPI bean so your documentation has a professional header.

Because the spec is generated from your actual code, the documentation stays in sync as your controllers change. This is the key advantage over hand-written docs.

Teams can feed the OpenAPI JSON into generators to produce typed clients in many languages, eliminating manual HTTP plumbing on the consumer side.

Test your understanding of API documentation.

You added springdoc-openapi, explored Swagger UI, and enriched docs with @Operation, @ApiResponses, and @Schema. Your API is now self-documenting and consumer-friendly.