스프링 swagger 사용하기

---

swagger?

swgger는 api문서를 자동으로 만들어주는 라이브러리이다.

단순 문서 뿐 아니라 API를 문서내에서 parameter를 넣어가며 바로바로 실행 해볼 수 있다.

• rest api 제작 후 따로 테스트 페이지나 postman으로 실행해보는 대신 swagger 문서 만들어서 실행 가능.
• 복잡하지 않은 시스템이라면 rest api 서버에 swagger를 적용시켜두고, 해당 api를 호출하는 작업자에게 뭐 복잡하게 설명하고 문서 만들 것 없이 swagger 문서 url만 보내서 알아서 작업하게 할 수 있음.

---

사용하기

Gradle 추가

implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

설정클레스

@Configuration
@EnableWebMvc
public class SwaggerConfig {

    private ApiInfo swaggerInfo() {
        return new ApiInfoBuilder().title("IoT API")
                .description("IoT API Docs").build();
    }

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(swaggerInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.nahwasa.iot.controller"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false);
    }

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }
}

'.basePackage()' 부분에 Swagger를 적용할 패키지 지정. 해당 패키지 이하의 모든 rest api가 자동으로 swagger 문서로 생성됨. (이하 예시에서는 'com.nahwasa.iot.controller' 패키지 이하를 모두 적용)
이 때, 해당 패키지 내에 포함되지만 Swagger 문서로 만들고 싶지 않을 경우 (예를들어 테스트용 컨트롤러나 api 작업자에게 보이기 싫은 api 등) 해당 컨트롤러에 @ApiIgnore 어노테이션을 추가하여 제외시킬 수 있음.

@Controller
@ApiIgnore
@RequestMapping("/")
public class IoTDevTestController extends IoTBaseController {
   ...

컨트롤러에 직접적용

@Controller
@RequiredArgsConstructor
@Tag(name = "Post", description = "게시물 api")
@RequestMapping("/api/v1")
public class PostApiController {

@GetMapping("/numble11/post")
	@Operation(summary = "모든게시물 가져오기", description = "모든 게시물을 가져오는 메서드입니다.")
	public ResponseEntity getAllPost(){
		List<Post> findPosts = postService.findPost();
        ...

나는 프로젝트에서 팀원분이 한거 따라 컨트롤러에 각각 지정해주었다.

---

직접 적용한 swagger

작동도 잘한다.