Swagger 프로젝트 적용과 어노테이션

Swagger란?

API들이 가지고 있는 스펙(spec)을 명세, 관리할 수 있는 프로젝트

왜 사용하는가?

협업을 진행하거나 이미 만들어져 있는 프로젝트에 대해 유지보수를 진행하게 되면 구축되어 있는 API서버가 어떤 스펙을 가지고 있는지 파악해야한다. 이러한 스펙 들을 직접 문서로 작성하게 되면 API가 변경될 때 마다 문서를 수정해야한다. 즉, 유지보수가 어려움.

이러한 어려움을 덜어주기 위해 만들어진 것이 Swagger이다.

프로젝트에 적용하는 방법

1. pom.xml 수정

<!-- Swagger -->

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.6.1</version>
</dependency>


<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.6.1</version>
</dependency>

2 SwaggerConfig 생성

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {

  @Bean
  public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("BoardWeb.controller"))
              .paths(PathSelectors.any())
              .build();

  }
}

3. dispathcer-servlet.xml 수정

<context:component-scan base-package="BoardWeb.swagger"/>

<!-- swagger -->
<bean class="BoardWeb.swagger.SwaggerConfig"/>
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"></mvc:resources>
<mvc:resources location="classpath:/META-INF/resources/webjars/"  mapping="/webjars/**"></mvc:resources>

4. http://localhost:8080/swagger-ui.html 접속

Swagger 관련 어노테이션

@GetMapping("/post")
@ApiOperation(value="사용자 정보 조회", notes="사용자 정보를 조회")
@CrossOrigin(origins = "http://localhost:3000")
public List goodPersons(){
return personRepository.findAll();
}

@PostMapping("/post")
@ApiOperation(value="사용자 정보 저장", notes="사용자 정보를 저장합니다")
@CrossOrigin(origins = "http://localhost:3000")
public void registration(@ModelAttribute("personForm") Post postForm) {
System.out.println(postForm);
personService.savePost(postForm);
}

@ApiOperation을 사용하여 해당 API에 대한 설명을 추가할 수 있다.
@ApiParam을 사용하여 매개 변수에 대한 세부 정보를 추가하거나 고드에서 읽을 때 값을 변경할 수 있다.

@Controller
@RequestMapping(value = "컨트롤러가 매핑되는 URL PATH")
@Api(value = "컨트롤러가 매핑되는 URL PATH", description = "controller 에 대한 설명을 써준다") // swagger annotation
public class SampleAPIController {
  @ApiOperation(        // swagger annotation
          value = "개별 API 에 대한 소개",
          notes = "개별 API 에 대한 설명",
          response = SampleResponseObject.class, responseContainer = "List"
  )
  @RequestMapping(value = "/{pathVariable}", method = RequestMethod.GET)
  public ResponseEntity<Collection<SampleResponseObject>> sendGetAPI(
          @ApiParam(value = "pathVariable 에 대한 설명", required = true)
          @PathVariable String pathVariable,
          @ApiParam(value = "파라미터에 대한 설명")
          @RequestParam(value = "limits", required = false) Integer limits,
          @ApiParam(value = "파라미터에 대한 설명")
          @RequestParam(value = "rollbackOptions", required = false) String rollbackOptions,
          @ApiParam(value = "Body 에 대한 설명", required = true)
          @RequestBody SampleRequestObject sRequestObject)

Swagger 오류, 해결방법

swagger-ui.html에 접속했을 때 500오류가 났다.
아래 1번과 2번중 하나를 적용하여 해결할 수 있다.

1. dipatcher-servlet.xml 코드 추가

2. SwaggerConfig에 @EnalbeWebMvc 어노테이션 추가

@EnablewebMvc 는 어노테이션 기반의 SpringMVC를 구성할 때 필요한 Bean 설정들을 자동으로 해주는 어노테이션이다.
기본적으로 등록해주는 Bean들 이외에 추가적으로 개발자가 필요로 하는 Bean들의 등록을 손쉽게 할 수 있도록 도와준다.

출처 참고자료

https://ttubeoki.tistory.com/20
https://www.baeldung.com/swagger-apiparam-vs-apimodelproperty
https://galid1.tistory.com/532
https://mrsence.tistory.com/56