[Spring] Swagger(스웨거) (2/2)

Swagger 의 활용 예제소스를 좀 더 추가하고자 스웨거 두번쨰 글을 올린다.

 

Controller

@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

@Entity
public class Post {

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

    @Column(nullable = false)
    private String title;

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

 

config

@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:{포트번호}/swagger-ui.html 로 접속하면 아래와 같은 화면이 보여진다.

 

** http://localhost:{포트번호}/swagger-ui.html 로 접속하는 이유는

springfox-swagger-ui 에서 만들어주기 때문이다.

 

 

Docket

• Swagger 설정을 할 수 있게 도와주는 클래스이다.
• useDefaultResponseMessages()
  • false로 설정하면 불필요한 응답코드와 설명을 제거할 수 있다.
  • Default 일때

    

  • false 일때

    

• groupName()
  • 만약 Bean이 하나라면 생략이 가능하지만 위의 코드와 같이 Bean이 여러 개면 명시해줘야한다.. Bean이 여러 개면 groupName이 출동하여 오류를 발생하기 때문. 그렇게 groupName를 명시하게되면 화면 우측상단에서 아래 이미지와 같은 List를 볼 수 있다.
  
• select()
  • ApiSelectorBuilder를 생성하여 apis()와 paths()를 사용할 수 있게 해준다.
• apis()
  • api가 작성되있는 패키지를 지정한다.
  • 저는 javable > controller 안에 api controller가 있기 때문에 basePackage를 javable.controller로 지정했다.
•  paths()
  • apis()로 선택된 API중 원하는 path를 지정하여 문서화할 수 있다. 지금은 PathSelectors.ant("/posts/**") 이렇게 설정했기때문에 /posts에 관한 API를 문서화해서 볼 수 있다.
  • PathSelectors.any()로 설정하면 패키지 안에 모든 API를 한 번에 볼 수 있지만 API가 많아지면 보기 힘든것이 단점.

 

 

ApiInfo

 

SwaggerConfig에 아래와 같이 ApiInfo를 추가하면 UI커스텀이 가능하다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "title",
                "description",
                "version",
                "https://win-bro.tistory.com",
                new Contact("Contact Me", "https://win-bro.tistory.com/", "newhendrick@gmail.com"),
                "tigger Licenses",
                "https://win-bro.tistory.com",
                new ArrayList<>()
        );
    }
}

 

ApiInfo의 생성자 파라미터는 다음과 같다.

public ApiInfo(
    String title, 			// 1
    String description, 		// 2
    String version, 			// 3
    String termsOfServiceUrl, 		// 4
    Contact contact, 			// 5
    String license, 			// 6
    String licenseUrl, 			// 7
    Collection<VendorExtension> vendorExtensions)

 

1. - title부분.   원하는 문자열을 넣어준다.
2. - description부분.   설명은 1번과 같음.
3. - version부분. 설  명은 1번과 같음.
4. - termsOfServiceUrl부분.   Terms of service를 클릭했을 때 보내고 싶은 URL를 적으면 된다.
5. - Contact부분의 첫 번째 파라미터와 두 번째 파라미터 설정.  5번을 클릭하면 두 번째 파라미터에 설정한 URL로 이동할 수 있다.
6. - Contact부분의 첫 번째 파라미터와 세 번째 파라미터 설정. Contact Me는 5번 설명과 동일하고, 클릭하면 세 번째 파라미터에 설정한 이메일 주소로 메일을 보낼 수 있다.
7. - license와 licenseUrl부분. license로 화면에 명시할 수 있고, 7번을 클릭하면 licenseUrl에 설정한 URL로 이동할 수 있다.

 

 

 

 

참고 :

[SpringBoot] Swagger - API Docs 자동화

Springfox Reference Documentation

https://tecoble.techcourse.co.kr/post/2020-08-31-spring-swagger/