Spring RESTful Web3

Rest API Documentation 사용

사용자 관리 REST API에 개발자 문서 도움말 페이지를 생성하겠습니다. REST WEB API에서 설계, 개발, 문서화, 그리고 사용에 관련해서 지원을 해주는Swagger라는 오픈소스를 통해서 Documentation을 만들겠습니다.

Swagger

pom.xml에 Dependencies를 추가 후 maven build를 다시 실행합니다.

//pom.xml
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

그리고 config라는 프로젝트를 생성해 SwaggerConfig라는 클래스를 생성합니다. Docket이라는 반환값을 가지고 있는 api 메서드를 만들겠습니다. Docket이라는 클래스 이름으로 반환하면 가지고 있는 문서의 내용을 documentation화를 할 수 있습니다. 매개변수 타입으로 DocumentationType을 지정합니다.

// restfulwebservice1/config/SwaggerConfig.java

@Configuration // 설정과 관련된 annotation
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2);

    }
}

/v2/api-docs라는 URI로 접속을 하면 JSON형태의 파일로 문서가 보입니다.그리고 /swagger-ui/index.html라는 URI로 접속을 하면 HTML 파일 형태로 문서가 보입니다.

hello-world-controller에 들어가면 이전에 만들었던 메서드가 소개되어있고, 필요한 파라미터, 어떤 반환값, status code가 어떤 것이 있는 지를 확인할 수 있습니다.

swagger-ui-page에는 개발사나 사용자들이 커스텀해서 사용할 수 있습니다.

Customize Swagger Documentation

SwaggerConfig 클래스에 연락처 정보를 위한 contact 객체를 생성합니다.

//config/SwaggerConfig.java

@Configuration
public class SwaggerConfig {
    private static final Contact DEFAULT_CONTACT
    = new Contact("TanonKim", "https://springworld.site", "robbins4bos@gmail.com"); //contact 객체

	// 상수로 만들어 항목 고정 (변경할 필요 없음)
    private static final ApiInfo DEFAULT_API_INFO = new ApiInfo("Awesome API Title",
            "User Management REST API service", "1,0", "urn:tos",
            DEFAULT_CONTACT, "Nginx",
            "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<>());

    private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES = new HashSet<>(
            Arrays.asList("application/json", "application/xml")
    );

DEFAULT_PRODUCES_AND_CONSUMES를 통해 어떠한 형태로 데이터를 사용할 수 있는지 문서 타입을 지정합니다. asList라는 메서드는 배열형태의 데이터 값을 리스트로 바꿔주는 유틸리티입니다.

그리고 Docket 객체에서 다음 줄에 apiInfo를 지정하고, produces에 대한 정보를 지정하고 consumes에 대한 정보도 지정합니다.

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(DEFAULT_API_INFO)
                .produces(DEFAULT_PRODUCES_AND_CONSUMES)
                .consumes(DEFAULT_PRODUCES_AND_CONSUMES);
    }
}

도메인에 대한 정보도 커스텀할 수 있습니다.

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description = "사용자 상제 정보를 위한 도메인 객체")
public class User {
    private Integer id;

    @Size(min = 2, message = "Name은 2글자 이상 입력해주세요")
    @ApiModelProperty(notes = "사용자 이름을 입력해주세요")
    private String name;
    @Past
    @ApiModelProperty(notes = "사용자 등록일을 입력해주세요")
    private Date joinDate;

    @ApiModelProperty(notes = "사용자 패스워드를 입력해주세요")
    private String password;
    @ApiModelProperty(notes = "사용자 주민번호를 입력해주세요")
    private String ssn;
}