이번에는 swagger를 적용하는 법을 알아 보겠습니다.
swagger
스웨거(Swagger)는 Open Api Specification(OAS)를 위한 프레임워크 입니다.
API들이 가지고 있는 스펙(spec)을 명세, 관리할 수 있는 프로젝트 입니다. 협업을 진행하거나 이미 만들어져 있는 프로젝트에 대해 유지보수를 진행하게 된다면 구축되어 있는 API서버가 어떤 스펙을 가지고 있는지 파악해야 합니다. 이러한 스펙을 정리하기 위해 API 문서화 작업을 하게 되며, 위의 과정을 직접 손으로 하게되는 경우 작업에 착수하기 전에 API의 명세와 문서를 작성하고, API가 수정될 때 마다 문서도 같이 수정해줘야 불편함이 동반하게 됩니다. 이러한 불편함을 조금이나마 줄여주기 위해 개발된 것이 이름하여 "Swagger Project" 입니다.
Swagger의 5가지 기능
- API 디자인
Swagger-editor를 통해 api를 문서화하고 빠르게 명세할 수 있습니다. - API Development
Swagger-codegen을 통해 작성된 문서를 통해 SDK를 생성하여 빌드 프로세스를 간소화 할 수 있도록 도와줍니다. 문서를 통해 실행하면 프로토 타입 코드를 생성해주는데 파일 구조가 정해져있는것 같습니다. - API Documentation
Swagger-UI를 통해 작성된 API를 시각화시켜 줍니다. - API Testing
Swagger-Inspector를 통해 API를 시각화 하고 빠른 테스팅을 진행할 수 있습니다. - Standardize
Swagger-hub를 통해 개인, 팀원들이 API정보를 공유하는 Hub입니다.
참고 : https://swagger.io/
swagger 적용해보기
의존성 주입
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency>
swagger설정
swagger 설정을 위해 SwaggerConfig 클래스를 생성합니다.
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket swaggerApi() { return new Docket(DocumentationType.SWAGGER_2) .useDefaultResponseMessages(false) .groupName(version) .select() .apis(RequestHandlerSelectors.basePackage("com.victolee.swaggerexam.api.v2")) .paths(PathSelectors.ant("/v2/api/**")) .build() .apiInfo(swaggerInfo()); } private ApiInfo swaggerInfo() { return new ApiInfoBuilder() .title("swagger sampleAPI") .description("Sswagger API 입니다.") .license("L&D System") .licenseUrl("http://www.swaggerSample.com") .version("1") .build(); } }
@EnableSwagger2
Swagger2 버전을 활성화 하겠다는 어노테이션입니다.
Docket
Swagger 설정의 핵심이 되는 Bean입니다.
API 자체에 대한 스펙은 컨트롤러에서 작성합니다.
참고 http://springfox.github.io/springfox/javadoc/2.9.2/springfox/documentation/spring/web/plugins/Docket.html
설정 정보
useDefaultResponseMessages()
false로 설정하면, swagger에서 제공해주는 응답코드 ( 200,401,403,404 )에 대한 기본 메시지를 제거합니다.
불필요한 응답코드와 메시지를 제거하기 위함이며, 컨트롤러에서 명시해줄 것입니다.
groupName()
Docket Bean이 한 개일 경우
기본 값은 default이므로, 생략가능
여러 Docket Bean을 생성했을 경우
groupName이 충돌하지 않아야 하므로, 여기서는 각 Docket Bean의 버전을 명시해줬습니다.
select()
ApiSelectorBuilder를 생성합니다.
apis()
api 스펙이 작성되어 있는 패키지를 지정합니다.
즉, 컨트롤러가 존재하는 패키지를 basepackage로 지정하여, RequestMapping( GetMapping, PostMapping ... )이 선언된 API를 문서화합니다.
paths()
apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화합니다.
apiInfo()
제목, 설명 등 문서에 대한 정보들을 보여주기 위해 호출합니다.
파라미터 정보는 다음과 같습니다.
public ApiInfo( title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions )
그리고 실행을 시켜봅니다.
url : localhost:8080/swagger-ui.html
swagger에서 지원해주는 ui로 swagger가 실행된 것을 확인 할 수 있습니다.
컨트롤러 작성해보기
@RestController @Api(value = "BoardController V2") @RequestMapping("/v1/api") public class BoardControllerV1 { @ApiOperation(value = "exam", notes = "예제입니다.") @ApiResponses({ @ApiResponse(code = 200, message = "OK !!"), @ApiResponse(code = 500, message = "Internal Server Error !!"), @ApiResponse(code = 404, message = "Not Found !!") }) @GetMapping(value = "/board") public Map<String, String> selectOneBoard(@ApiParam(value = "게시판번호", required = true, example = "1") @RequestParam String no) { Map<String, String> result = new HashMap<>(); result.put("author", "victolee"); result.put("content", "V1 API 내용"); return result; } }
@Api
해당 클래스가 Swagger 리소스라는 것을 명시합니다.
value
태그를 작성합니다.
tags
사용하여 여러 개의 태그를 정의할 수도 있습니다.
@ApiOperation
한 개의 operation(즉 API URL과 Method)을 선언합니다.
value
API에 대한 간략한 설명(제목같은 느낌으로)을 작성합니다.
notes
더 자세한 설명을 작성해줍니다.
@ApiResponse
operation의 가능한 response를 명시합니다.
code
응답코드를 작성합니다.
message
응답에 대한 설명을 작성합니다.
responseHeaders
헤더를 추가할 수도 있습니다.
@ApiParam
파라미터에 대한 정보를 명시합니다.
value
파라미터 정보를 작성합니다.
required
필수 파라미터이면 true, 아니면 false를 작성합니다.
example
테스트를 할 때 보여줄 예시를 작성합니다.
swagger 어노테이션이 더 많지만 주로 사용하는것만 설명했습니다.
여기서 초록색 버튼의 "Try it out" 버튼을 클릭하면 실제 API를 바로 테스트 해볼 수 있습니다.
