[Spring Boot] RESTful Service 강의 정리 (7) - Configuring Auto Generation of Swagger Documentation / 개발자 도움말 페이지 생성

 

[Spring Boot] RESTful Service 강의 정리 (6) - Implementing HATEOAS / level3단계의 REST API 구현

---

Swagger 

Spring REST API Documentation - 개발자 도움말 페이지 생성

---

1. Swagger의 간단한 구현 방법

1) pom.xml -> add dependencies

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

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

 

2) Configuration class 생성

package com.example.restfulwebservice.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration // 설정에 관련된 정보를 뜻하는 어노테이션
@EnableSwagger2 // 스웨거 용도로 사용하겠다는 어노테이션
public class SwaggerConfig {

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

 

-> 확인하는 링크 2가지 http://localhost:8088/v2/api-docs http://localhost:8088/swagger-ui.html

 

http://localhost:8088/v2/api-docs

 

http://localhost:8088/ swagger-ui.html

---

2. Swagger Documentation Customizing

- SwaggerConfig

package com.example.restfulwebservice.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

@Configuration // 설정에 관련된 정보 어노테이션
@EnableSwagger2 // 스웨거 용도로 사용
public class SwaggerConfig {

    // static final로 생성하는 이유 : 한번 생성이되면 변경이 되지않는 정보들이기 때문에

    // 사용자 정보를 나타내는 컨택트 객체
    private static final Contact DEFAULT_CONTACT = new Contact("Howl Lee",
            "http://www.joneconsulting.co.kr","gpflavvvvv@gmail.com");

    // API 정보
    private static final ApiInfo DEFAULT_API_INFO = new ApiInfo("Awesome API Title",
            "My User management REST API service","1.0","urn:tos",
            DEFAULT_CONTACT, "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<>());

    // 문서 타입 지정
    // asList() : 배열형태의 데이터 값을 리스트로 바꿔주는 메소드
    private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES
            = new HashSet<>(Arrays.asList("application/json","application/xml"));

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

 

 

 

- User (domain)

package com.example.restfulwebservice.user;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.validation.constraints.Past;
import javax.validation.constraints.Size;
import java.util.Date;

@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;
}

 

코드 작성 전(변경 전)

 

ApiModel / ApiModelProperty 작성 후

 

ApiModel / ApiModelProperty 작성 후