[Spring Boot를 이용한 RESTful Web Services 개발] 29~30강

Swagger 설명

• 설계, 빌드, 문서화, 사용에 관련된 작업을 지원해주는 오픈소스 프레임워크
• 사용자, 개발자에 관련된 Documentation 페이지를 만들 수 있음

 

REST API Documentation을 위한 Swagger 사용

• pom.xml 파일에 의존성 추가
• 원래는 주석 내용으로 추가해야하나 Spring boot 2.6버전 이후에 spring.mvc.pathmatch.matching-strategy 값이 ant_apth_matcher에서 path_pattern_parser로 변경되면서 몇몇 라이브러리(swagger포함)에 오류가 발생하는 문제로 수정. (링크 참고)

<!--        <dependency>-->
<!--            <groupId>io.springfox</groupId>-->
<!--            <artifactId>springfox-swagger2</artifactId>-->
<!--            <version>2.9.2</version>-->
<!--        </dependency>-->
<!--        <dependency>-->
<!--            <groupId>io.springfox</groupId>-->
<!--            <artifactId>springfox-swagger-ui</artifactId>-->
<!--            <version>2.9.2</version>-->
<!--        </dependency>-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

• application.yml파일에 추가

spring:
  messages:
    basename: messages
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

• config 패키지 생성 -> SwaggerConfig 클래스 생성
• 스프링 빈 프로젝트에서 Configuration과 같이 특별한 용도를 가지고 있는 빈으로 등록하고 싶은 경우 Class 선언 상단에 필요한 어노테이션을 추가해야 함
• @Configuration 어노테이션 추가하여 설정에 해당 빈 올리기, @EnableSwagger2 어노테이션 추가하여 swagger 용도로 사용하는 것 설정 

package com.example.restfulwebservice.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    // api와 관련된 Documentation을 만들기 때문에 메소드 명을 api로 설정
    // Docket 형으로 반환하여 가지고 있는 문서의 내용을 Documentaion화 해줌
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

Swagger file에 의해서 만들어진 내용이 Json 데이터 타입으로 보여지고 있음을 확인

선언한 User 클래스가 분석되어진 것을 확인할 수 있음

현재 프로젝트가 가지고 있는 Controller를 swagger가 분석해서 만들어준 페이지를 확인할 수 있음

• Swagger ui 페이지는 개발 회사나 일반 사용자들이 커스터마이징 해서 사용할 수 있도록 지원해주는 도구.
• v2/api-docs 페이지에서 전달되어진 값을 토대로 ui 페이지를 직접 커스터마이징 해서 작성할 수 있음

 

Swagger Documentation 구현 방법

• Swagger Documentation에 API 정보, 프로듀서 정보, 컨슈머 정보 등을 추가하여 커스터마이징 하기
• SwaggerConfig 클래스 수정

package com.example.restfulwebservice.user;

import com.fasterxml.jackson.annotation.JsonFilter;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.validation.constraints.Past;
import javax.validation.constraints.Size;
import java.util.Date;

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description = "사용자 상제 정보를 위한 도메인 객체")
public class User {
    private Integer id;
    @Size(min=2, message = "Name은 2글자 이상 입력해주세요.")
    @ApiModelProperty(notes = "사용자 이름을 입력해 주세요")
    private String name;
    @Past
    @ApiModelProperty(notes = "사용자 등록일을 입력해 주세요")
    private Date joinDate;
    @ApiModelProperty(notes = "사용자 패스워드를 입력해 주세요")
    private String password;
    @ApiModelProperty(notes = "사용자 주민번호를 입력해 주세요")
    private String ssn;
}

위에서 지정해준 설정 정보가 잘 들어가 있는 것을 확인할 수 있음

 

도메인 객체에 Description 추가

• User 도메인 객체에 대한 Title과 Description 정보 추가
• User 클래스 수정

package com.example.restfulwebservice.user;

import com.fasterxml.jackson.annotation.JsonFilter;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.validation.constraints.Past;
import javax.validation.constraints.Size;
import java.util.Date;

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description = "사용자 상제 정보를 위한 도메인 객체")
public class User {
    private Integer id;
    @Size(min=2, message = "Name은 2글자 이상 입력해주세요.")
    @ApiModelProperty(notes = "사용자 이름을 입력해 주세요")
    private String name;
    @Past
    @ApiModelProperty(notes = "사용자 등록일을 입력해 주세요")
    private Date joinDate;
    @ApiModelProperty(notes = "사용자 패스워드를 입력해 주세요")
    private String password;
    @ApiModelProperty(notes = "사용자 주민번호를 입력해 주세요")
    private String ssn;
}

설정한 description이 잘 지정되어 있는 것을 확인할 수 있음

ui 페이지에서도 설정한 description이 잘 지정되어 있는 것을 확인할 수 있음