[KSUG Spring Boot Study] REST API 명세 문서화

• API 개발 과정에서 계속 변경되므로 작성한 명세 문서도 주기적인 업데이트 필요
• Swagger라는 오픈소스 프로젝트를 넣어보자

Swagger

• pom.xml 파일 의존성 추가

		<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
			<version>2.6.0</version>
		</dependency>

• config 폴더 만들어서 SwaggerConfiguration 넣기

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfiguration {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().components(new Components()).info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("Spring Boot Open API Test with Swagger")
                .description("설명 부분")
                .version("1.0.0");
    }
}

 

http://localhost:8080/swagger-ui/index.html → 접속

 

Swagger 꾸미기

• GetController에서 Swagger 설명을 추가해보자

    // <http://localhost:8080/api/v1/get-api/request1?name=flature&email=thinkground.flature@gmail.com&organization=thinkground>
    @Operation(summary = "GET 메서드 예제", description = "@RequestParam을 활용한 GET 메서드")
    @GetMapping(value = "/request1")
    public String getRequestParam1(
            @Parameter(name = "name", description = "이름", required = true) @RequestParam String name,
            @Parameter(name = "email", description = "이메일", required = true) @RequestParam String email,
            @Parameter(name = "organization", description = "회사", required = true) @RequestParam String organization) {
        return name + " " + email + " " + organization;
    }

 

• Operation → 대상 API의 설명을 작성하기 위한 애너테이션
• Parameter → 매개변수에 대한 설명 및 설정을 위한 애너테이션