스프링 게시판 API 만들기 6

API 명시서를 한 번 작성해보려고 했는데, 옛날에 Swagger를 딱 한 번 썼던 기억이 있어서 Swagger로 간편하게! 알아서 작성되게! 해보려고 한다.

Spring boot 3 미만에서는 springfox-swagger2 와 springfox-swagger-ui 를 의존성 축라해서 사용해야 하지만, 3 이상부터는 그냥 하나의 의존성만 추가해주면 된다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

보면 이름이 다른 것을 알 수 있다. 구글링해서 찾아봤는데, 사람마다 하는 이야기가 달라서 좀 헷갈리긴 한다. 일단 swagger는 2020을 마지막으로 업데이트가 되지 않고 있다. 그 사이에 나온 게 SpringDoc(2019년)인데, 비교적 최근까지 업데이트가 되었다.

Springdoc은 Webflux라는 논 블록킹 비동기 방식의 웹 개발을 지원하도록 되어 있으며, springfox보다 더 사용하기 쉽다고 한다.(둘 다 심도있게 써보진 않아서 나는 비교하지 못하겠다.)

일단 한번 사용을 해보자.

---

application.properties 에 아래와 같이 등록해 줄 수 있다.

# spring doc
# springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/api-docs/json
springdoc.packagesToScan=com.hyeon.demo.controller
# springdoc.pathsToMatch=/boards

주석 처리되어 있는 것은 내가 추후에 쓰지 않으려고 한 것이다.

• springdoc.swagger-ui.path=/swagger-ui.html : HTML 페이지를 보여줄 url을
• springdoc.api-docs.path=/api-docs/json : json 페이지를 보여줄 url을 정한다.
• springdoc.packagesToScan=com.hyeon.demo.controller: API 문서를 작성할 패키지명을 넣어준다. 여러개 넣으려면 그냥 ,(쉼표) 써서 연결해 작성하면 된다.
• pringdoc.pathsToMatch=/boards : API 문서를 작성할 API 범위를 지정한다. /boards와 같이 쓰면 /boards 인 API 만 작성되어지고, /boards/** 와 같이 작성하면 /boards/ 하위 API 들이 다 작성되어진다.

여기 에서 더 다양한 값들을 찾아볼 수 있다.

그 후 나는 SwaggerConfig.java 를 생성하였다.

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("board-public")
                .pathsToMatch("/boards/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("board-admin")
                .pathsToMatch("/**")
                .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class)) //@Admin이 붙어 있는 Method만
                .build();
    }

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Board API")
                .description("Simple Board API")
                .version("v0.0.1"));
    }

}

GroupedOpenApi 같은 경우는 그룹을 생성해준다.
저렇게 생성해주면, 페이지를 열었을 때 아래와 같이 셀렉트 박스를 통해 선택할 수 있게 된다.

이 후 서버를 실행해보면, 아래와 같은 페이지가 나타난다.

추가적으로, .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class)) 에 있는 Admin.class 는 @interface 즉, 어노테이션이며 아래와 같이 선언만 해주었다.

public @interface Admin {

}

이 어노테이션이 달린 메서드만 추려내서 board-admin 그룹에 보이게 된다.

끝 -*