Swagger 기본 사용법 및 API 문서화

1. Swagger란

스웨거란 Web API를 자동 문서화 시켜주는 도구, API의 명세를 관리하기 위한 라이브러리다.
간단한 설정 및 어노테이션을 사용해 API가 어떤 역할을 하는지, 어떤 파라미터와 요청 정보를 요구하는지 기술 할 수 있다. 뿐만 아니라 API의 변경점이 생겼을때 자동으로 갱신되기 때문에 더욱 편리하다.

2. 설정법

2-1 프로젝트 환경설정

	implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
	runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
	runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'
	implementation group: 'com.auth0', name: 'java-jwt', version: '4.0.0'
	implementation 'io.springfox:springfox-boot-starter:3.0.0'
	implementation 'io.springfox:springfox-swagger-ui:3.0.0'

2-2 의존성 추가

먼저 의존성을 추가한다.
	implementation 'io.springfox:springfox-boot-starter:3.0.0'
	implementation 'io.springfox:springfox-swagger-ui:3.0.0'
gradle 기준으로 bulid.gradle에 해당 의존성을 추가한다.

2-3 설정 파일 추가

@Configuration
@EnableSwagger2
@EnableAutoConfiguration
public class SwaggerConfiguration {


    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gaubiz.gorder.api"))
                .paths(PathSelectors.any())
                .build()
                .globalResponses(HttpMethod.GET, GlobalResponses())
                .globalResponses(HttpMethod.POST, GlobalResponses());
    }



    private List<Response> GlobalResponses() {
        List<Response> responses = new ArrayList<>();

        responses.add(new ResponseBuilder()
                .code("200")
                .description(getMessageSource().getMessage("HTTP_OK",null,Locale.getDefault()))
                .build());

        responses.add(new ResponseBuilder()
                .code("400")
                .description(getMessageSource().getMessage("HTTP_BAD_REQUEST",null, Locale.getDefault()))
                .build());

        responses.add(new ResponseBuilder()
                .code("500")
                .description(getMessageSource().getMessage("HTTP_SERVER_ERROR",null,Locale.getDefault()))
                .build());

        return responses;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("G-Order v1.0")
                .description("G-Order API")
                .version("1.0")
                .build();
    }
}
@EnableSwagger2 어노테이션을 추가해 기능을 활성화 시킨다.
Doket을 Bean으로 등록하여 설정을 한다.

@Bean
public Docket api() {
return new Docket(DocumentationType.OAS_30)
   // 타입을 OAS 3.0 으로 설정
.useDefaultResponseMessages(false)
   // 기본으로 노출되는 HTTP Method를 제거한다.
.apiInfo(apiInfo())
   // 문서의 기본 정보를 설정한다.
.select()
.apis(RequestHandlerSelectors.basePackage("com.gaubiz.gorder.api"))
// 문서화할 패키지를 지정한다.
.build()
.globalResponses(HttpMethod.GET, GlobalResponses())
   // GET 메소드에 대한 response 설정
.globalResponses(HttpMethod.POST, GlobalResponses());
   // POST 메소드에 대한 response 설정

.globalResponses(HttpMethod.DELETE, GlobalResponses())
// DELETE 메소드에 대한 response 설정
.globalResponses(HttpMethod.PATCH, GlobalResponses())
// PATCH 메소드에 대한 reponse 설정
.globalResponses(HttpMethod.PUT, GlobalResponses());
// PUT 메소드에 대한 reponse 설정
}

private List<Response> GlobalResponses() {
List<Response> responses = new ArrayList<>();

responses.add(new ResponseBuilder()
// response 객체에 추가
.code("200")
// 200 코드 설정
.description(getMessageSource().getMessage("HTTP_OK",null,Locale.getDefault()))
// 설명 추가
.build());

responses.add(new ResponseBuilder()
.code("400")
.description(getMessageSource().getMessage("HTTP_BAD_REQUEST",null, Locale.getDefault()))
.build());

responses.add(new ResponseBuilder()
.code("500")
.description(getMessageSource().getMessage("HTTP_SERVER_ERROR",null,Locale.getDefault()))
.build());

return responses;
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("G-Order v1.0")
// api 제목
.description("G-Order API")
// api 설명
.version("1.0")
// 버전
.build();
}

2-4 컨트롤러 설정

컨트롤러에 이름과 노출될 값 설정을 한다.

@Api(tags = {"계정 API"})
@RestController
@RequestMapping("/account")
public class AccountController {
    
    @ApiOperation(value = "서브 비활성화")
    @PutMapping("/active")
    public ResponseEntity<?> subActive(
        @Validated(Groups.subActiveGroup.class)
        @RequestBody Sub sub
    ){
        return accountService.updateSubActive(sub);
    }
    ...
 }

public class Account {
    @ApiModelProperty(
            value = "계정 고유번호"
            , example = "G15881581"
    )
    @NotBlank(
            groups = {Groups.loginGroup.class},
            message = "{message.003}"
    )
    private String accountSerial;

    @ApiModelProperty(
            value = "계정명"
            , example = "한신포차"
    )
    @NotBlank(
            groups = {Groups.registerGroup.class},
            message = "{message.001}"
    )
    private String accountName;

    @ApiModelProperty(
            value = "계정 연락처"
            , example = "15881581"
    )
    @Min(
            value = 0,
            groups = {Groups.registerGroup.class},
            message = "{message.002}"
    )
    private Integer accountTel;

    @ApiModelProperty(
            value = "계정 타입"
            , example = "MASTER"
    )
    @NotBlank(
            groups = {Groups.loginGroup.class, Groups.registerGroup.class},
            message = "{message.004}"
    )
    private String accountType;
}

class : @Api(tag = {"API의 이름"}

method : @ApiOperation(value = "해당 메소드의 이름")

변수 : @ApiModelProperty(value = "값", example = "예시 값")

으로 설정한다. 이것의 결과는 아래와 같다.