Swagger 라이브러리를 사용하여 API 내용 정리하기

web/Spring|2018. 8. 7. 00:08

Web 개발을 진행하다보면 다양한 API를 개발하게 된다.

하지만 정리하기가 쉽지 않고 이를 위해서 인터페이스정의서를 계속 정리하기도 사실 쉽지 않다. 
이를 위해서 한번에 API 내용이 정리되어 한눈에 볼 수 있도록 제공해주는 library가 있다. 이 library인 swagger를 적용해보자.

1. 라이브러리 추가
Swagger 사용을 위한 라이브러리를 gradle에 추가하자.

1
2
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.5.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.5.0'
cs


2. Swagger 설정 관련 내용 Configuration 클래스 생성

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
package com.wedul.common.config;
 
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
/**
 * Swagger 사용을 위한 설정 클래스
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
 
    /**
     * 설정
     *
     * @return the docket
     */
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any()) // 현재 RequestMapping으로 할당된 모든 URL 리스트를 추출
                .paths(PathSelectors.ant("/user/**")) // /user/** 인 URL들만 추출
                .build();
    }
 
}
cs


Docket의 더 많은 사용법은 아래 사이트 참고.
https://swagger.io/tools/swaggerhub/hosted-api-documentation/


3. Spring Security 사용시 권한 허용
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// 권한 허용 리스트
@Override
public void configure(WebSecurity web) throws Exception {
    // 허용되어야 할 경로들
    web.ignoring().antMatchers("/resources/**"
                               "/dist/**"
                               "/weather"
                               "/user/password/find",
                               "/user/join",
                               "/user/email",
                               "/user/nickname",
                               "/user/send/temppw",
                               "/findpw"
                               "/user/findpw",
                               "/user/cert/check",
                               "/join"
                               "/getLanguage/**",
                               "/getMessage",
                                "/api/**"); // #3
}
 
 
// resource 허용    
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/dist/**").addResourceLocations("/dist/");
 
    registry.addResourceHandler("/resources/**")
            .addResourceLocations("/WEB-INF/resources/");
 
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
 
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}
cs

이렇게 한 후 실행 시키면 다음과 같이 swagger-ui를 확인할 수 있다.


또한 각 상황에 대해 API를 호출하면서 header, body, response 등을 확인할 수 있다.


댓글()

Java Json Library Jacson Annotation 소개

web/Spring|2018. 5. 27. 19:14

restFul API를 만들다 보면, 어떤 항목을 serialize 제외하거나 null인 항목은 제외하거나 하는 작업이 필요로 할 때가 있다.

이를 Jackson 라이브러리의 Annotation을 사용하여 하는 방법을 확인해보자.

[Maven 셋팅]




1
2
3
4
5
6
7
8
9
10
11
<properties>
    <jackson.version>2.9.2</jackson.version>
</properties>
  
<dependencies>       
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${jackson.version}</version>
        </dependency>
</dependencies>
cs




예제로 사용될 Student Dto 클래스이다.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
package com.wedul.common.dto;
 
/**
 * 학생 DTO
 *
 * @class StudentDto.java
 * @author cjung
 * @since 2018. 4. 2.
 */
public class StudentDto {
    private String name;
    private String dept;
    private int age;
    
    public StudentDto() {}
    
    public StudentDto(String name, String dept, int age) {
        this.name = name;
        this.dept = dept;
        this.age = age; 
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
    public String getDept() {
        return dept;
    }
 
    public void setDept(String dept) {
        this.dept = dept;
    }
 
    public int getAge() {
        return age;
    }
 
    public void setAge(int age) {
        this.age = age;
    }
 
}
cs



그리고 요청을 받을 Controller 이다.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package com.wedul.common.controller;
 
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
 
import com.wedul.common.dto.StudentDto;
 
@RestController
@RequestMapping(value = "/student")
public class StudentCtrl {
    
    /**
     * 학생 정보 얻기
     * 
     * @return
     */
    @PostMapping("/get")
    public ResponseEntity<?> getStudent() {
        return ResponseEntity.ok(new StudentDto("wedul""weduls"28)); 
    }
}
cs


/cjungproject/student/get url을 호출하여 결과를 확인해보면 다음과 같이 나온다.




이 기본적인 기능에서 추가적으로 제공되는 Jackson Library 기능을 확인해보자.


1. Serializer/Deserialize 시 제외시킬 프로퍼티를 지정
@JsonIgnoreProperties을 사용하여 제외시킬 프로퍼티를 설정할 수 있다.

[설정방법]
1
2
3
4
5
@JsonIgnoreProperties(value = {"name", "dept"})
public class StudentDto {
    private String name;
    private String dept;
    private int age;
cs



[결과]





2. 전달될 프로퍼티를 다른이름으로 전송
- @JsonProperty를 이용하여 다른 이름으로 전송이 가능하다.

[설정]
1
2
3
4
5
6
7
8
9
public class StudentDto {
    @JsonProperty("userName")
    private String name;
 
    @JsonProperty("userDept")
    private String dept;
    
    @JsonProperty("userAge")
    private int age;
cs



[결과]




3. 프로퍼티가 notNull 이거나 notEmpty일경우에만 반환되도록 설정

- @JsonInclude을 사용하면 프로퍼티가 null 이나 empty 상태일때 전송되지 않도록 지정할 수 있다.

[설정]


1
2
3
4
5
6
7
8
9
public class StudentDto {
    @JsonInclude(JsonInclude.Include.NON_NULL)
    private String name;
 
    @JsonInclude(JsonInclude.Include.NON_EMPTY)
    private String dept;
    
    @JsonProperty("userAge")
    private int age;
cs



[결과]


위와 같이 전달할 경우. name과 dept가 null과 empty 상태이기 때문에 전송이 되지 않는것을 확인할 수 있습니다.





댓글()