Todo 플젝 - Swagger 옵션 추가

https://whats-this-i-dont-know.tistory.com/45?category=1112076 

swagger (개인 플젝)

 

Swagger UI를 사용하면 개발 팀이든 엔드 유저든 누구나 구현 로직 없이도 API 리소스를 시각화하고 상호 작용할 수 있도록 도와준다.(OAS(Open Api Specification)으로 API의 스펙을 관리)

Swagger는 OpenAPI 사양으로 자동 생성되며 시각적 문서를 통해 백엔드 구현 및 클라이언트 측 사용을 쉽게 할 수 있게 한다.

https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

Setting Up Swagger 2 with a Spring REST API | Baeldung

 

환경

• spring boot 2.7.2
• gradle
• swagger ui 3.0.0

 

Swagger 설정파일(기본)

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

https://swagger.io/blog/news/whats-new-in-openapi-3-0/

What is OpenAPI 3.0? | Swagger Blog

 

//@EnableSwagger2
@Configuration
public class SwaggerConfig {

//    Docket 설정 기본
//    @Bean
//    public Docket api() {
//        return new Docket(DocumentationType.OAS_30)
//                .select()
//                .apis(RequestHandlerSelectors.any())
//                .paths(PathSelectors.any())
//                .build();
//    }
    private String version;
    private String title;

    @Bean
    public Docket apiV1() {
        version = "V1";
        title = "todo API " + version;

        return new Docket(DocumentationType.OAS_30)
                .groupName(version)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.app.todo.api.v1"))
                .paths(PathSelectors.ant("/todo/V1/**"))
                .build()
                .apiInfo(apiInfo(title, version));
    }

    @Bean
    public Docket apiV2() {
        version = "V2";
        title = "todo API " + version;

        return new Docket(DocumentationType.OAS_30)
                .groupName(version)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.app.todo.api.v2"))
                .paths(PathSelectors.ant("/todo/V2/**"))
                .build()
                .apiInfo(apiInfo(title, version));
    }

    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfo(
                title,
                "Swagger로 생성한 API Docs",
                version,
                "www.start-any.com",
                new Contact("Contact Me", "www.start-any.com", "cksal4278@gmail.com"),
                "Licenses",
                "www.start-any.com",
                new ArrayList<>()
        );
    }
}

•  8081/V3
  • Swagger 3을 의미 2로 하면 v2로 뜸
  • basePackage는 requestMapping 위치 찾아서 맞춰줘야 api 잘 뜬다.

 

설정을 더 추가해보겠다.

 

api 컨트롤러에서

• @Api
  • api controller 설명
• @ApiOperation
  • value
    • 매개변수
  • notes
    • api 설명

이렇게 나온다.

 

다음으로는 response에 대한 글로벌 메시지 설정을 해보겠다.

해당 설정을 하게 되면 공통된 응답 메시지를 작성하고 깔끔해진다.

 

TODO

• 글로벌 메시지 설정
• 서버 껐다켜는거 귀찮으니 자동 반영 설정