[spring] swagger2로 API 명세서 만들기

Swagger 란

REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트이다.

 

swagger를 사용하는 이유는 코드 몇줄로 API 명세서를 작성해 사용할 수 있으며 테스트할 수 있는 UI도 제공한다.

또한 파라메터를 넣어보고 테스트도 할 수 있다. 

API 문서를 작성하는 시간도 줄이고 실시간으로 유지할 수 있다는 장점도 있다. 

 

 

 

사용방법

'3.0.0' 과 '2.9.2' 의 설정 방법이 다른데 나는 '2.9.2' 버전으로 진행했다. 

 

의존성 추가 

  - gradle

// swagger
compile 'io.springfox:springfox-swagger2:2.9.2'
compile 'io.springfox:springfox-swagger-ui:2.9.2'

   - pom.xml

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

 

 

사전 작업 

Controller와 Entity를 작성한다. 

 

@RequestMapping("/posts")
@RestController
public class PostController {

    private final PostService postService;

    public PostController(final PostService postService) {
        this.postService = postService;
    }

    @PostMapping
    public ResponseEntity<PostResponse> create(@RequestBody final PostRequest postRequest) {
        final PostResponse postResponse = postService.create(postRequest);
        return ResponseEntity.created(URI.create("/posts/" + postResponse.getId())).build());
    }

    @GetMapping
    public ResponseEntity<List<PostResponse>> findAll() {
        return ResponseEntity.ok(postService.findAll());
    }

    @GetMapping("/{postId}")
    public ResponseEntity<PostResponse> findById(@PathVariable final Long postId) {
        return ResponseEntity.ok(postService.findById(postId));
    }

    @PutMapping("/{postId}")
    public ResponseEntity<Void> update(@PathVariable final Long postId, @RequestBody PostRequest postRequest) {
        postService.update(postId, postRequest);
        return ResponseEntity.ok().build();
    }

    @DeleteMapping("/{postId}")
    public ResponseEntity<Void> delete(@PathVariable final Long postId) {
        postService.delete(postId);
        return ResponseEntity.noContent().build();
    }
}

@Entity
@Getter
public class Post {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String title;

    @Column
    private String content;
    
    // ...
}

 

swaggerConfig 클래스를 생성해준다. 

'3.0.0' 인 경우 @EnableSwagger2 를 사용하지 않아도 된다. 

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket apiV1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("groupName1")
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("javable.controller"))
                .paths(PathSelectors.ant("/posts/**")).build();
    }
    
    @Bean
    public Docket apiV2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .groupName("groupName2")
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("javable.controller"))
                .paths(PathSelectors.ant("/posts/**")).build();
    }
}

 

코드 작성이 끝나면 서버를 실행시켜 http://localhost:8080/swagger-ui.html 로 접속한다. 

 

• Docket
  • swagger설정을 할 수 있게 도와주는 클래스

 

 

 

 

 

 

 

 

 

 

참고

https://swagger.io/docs/specification/about/

About Swagger Specification | Documentation | Swagger

https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui