[Spring Boot 실습 #5] Swagger UI 활용 (1) - Swagger 정의 및 활용

Spring Boot : Swagger UI 활용 (1) - Swagger

spring fox 라이브러리의 Swagger UI를 활용하여 spring boot 프로젝트에 매핑된 controller 테스트

 

• Swagger : 정의, 활용
• 개발환경 : Java, Maven, Spring-fox
• 라이브러리 다운로드 (pom.xml)
• 설정 : application.properties / application.yml
• Hello World : 기본 호출 테스트 - default controller
• swagger 설정 추가
• 문자열 List 반환 테스트

 

# Swagger

 

Swagger 정의

Swagger는 JSON형태로 표시된 RESTful API에 대한 인터페이스 설명 언어 (Interface Description Language).

Swagger는 기타 다른 오픈소스 소프트웨어들과 조합하여 RESTful 웹서비스를 디자인, 구축, 문서화하는 작업 수행.

Swagger는 문서 자동화, 여러 프로그래밍 언어로 코드 생성, 테스트 케이스 생성 작업을 포함.

 

Swagger 활용 : API 개발; API간 통신; 문서화

 

API 개발

API 개발시 코드 자체에 기반한 Open API 문서를 자동으로 생성 가능

이는 프로젝트 내의 소스 코드의 API에 대한 설명을 포함하며, code-first 또는 bottom-up API 개발이라고 함.

Swagger Codegen 활용시 개발자는 Open API 문서로부터 소스코드를 decoupling 하여, 직접 API 디자인으로부터 client나 server 코드를 생성 가능

 

API간 통신

Codegen 프로젝트 활용할 경우, 사용자는 직접 Open API 문서로부터 client SDK 생성할 수 있어 사람이 생성한 코드의 필요성 감소.

 

API 문서화

Open API 문서를 설명할 때, Swagger 오픈소스로 Swagger UI를 통해서 직접 API 활용(통신)이 가능.

Swagger UI는 HTML 기반 사용자 인터페이스로 다수의 API들과 직접 연결이 가능.

해당 인터페이스를 통해 직접 API 요청을 하거나 기타 옵션들을 찾을 수 있음

 

 

API 개발

API 개발시 코드 자체에 기반한 Open API 문서를 자동으로 생성 가능

 

 

 

---

참고

Wikipedia - Swagger (software)

 

Swagger is an Interface Description Language for describing RESTful APIs expressed using JSON. Swagger is used together with a set of open-source software tools to design, build, document, and use RESTful web services. Swagger includes automated documentation, code generation (into many programming languages), and test-case generation.

 

 

Usage

Swagger's open-source tooling usage can be broken up into different use cases: development, interaction with APIs, and documentation.

 

Developing APIs

When creating APIs, Swagger tooling may be used to automatically generate an Open API document based on the code itself. This embeds the API description in the source code of a project and is informally called code-first or bottom-up API development.

 

Alternatively, using Swagger Codegen, developers can decouple the source code from the Open API document, and generate client and server code directly from the design. This makes it possible to defer the coding aspect.

 

Interacting with APIs

Using the Swagger Codegen project, end users generate client SDKs directly from the OpenAPI document, reducing the need for human-generated client code. As of August 2017, the Swagger Codegen project supported over 50 different languages and formats for client SDK generation.

 

Documenting APIs

When described by an OpenAPI document, Swagger open-source tooling may be used to interact directly with the API through the Swagger UI. This project allows connections directly to live APIs through an interactive, HTML-based user interface. Requests can be made directly from the UI and the options explored by the user of the interface.