Kotlin × Spring으로 만드는 API & 문서

이번에는 Springfox에서 Swagger를 자동 생성하는 방법을 소개합니다. 먼저 SpringBoot에서 API를 만들고 해당 코드에서 문서를 자동으로 생성합니다. API를 작성부터 문서화까지 10분 정도로 할 수 있다고 생각합니다.

Spring Initializr로 프로젝트 만들기

h tps : // s rt. sp 링 g. 이오/
에서 Spring 프로젝트를 만듭니다.

이번에는

Gradle Project

Kotlin

Spring Boot 2.1.4

Web

를 선택했습니다.

Spring Boot에서 Rest API 구현

HelloController 클래스를 작성합니다.
이번에는 /hello에 GET 요청이있을 때 응답을 반환하는 프로세스를 구현합니다.

HelloController.kt

package com.example.demo.controller

import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping
class HelloController {

    @GetMapping("/hello")
    fun hello(@RequestParam(value = "name", required = false, defaultValue = "everyone") name: String): String {
        return "Hello, $name!"
    }
}

./gradlew bootRun 혹은 IntelliJ내에서 Run 해 움직입니다.

실행 예

$ curl http://localhost:8080/hello?name=Bob
Hello, Bob!

Springfox에서 문서 만들기

build.gradle에 swagger에 대한 설정을 추가합니다.// 追加 의 2 행 이외는 모두 Iniitalizr 로 생성한 채입니다.

build.gradle

// 省略

dependencies {
    compile 'io.springfox:springfox-swagger2:2.9.2' // 追加
    compile 'io.springfox:springfox-swagger-ui:2.9.2' // 追加
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'com.fasterxml.jackson.module:jackson-module-kotlin'
    implementation 'org.jetbrains.kotlin:kotlin-reflect'
    implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk8'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

// 省略

DemoApplicaion.kt에 @EnableSwagger2를 추가합니다.

DemoApplication.kt

package com.example.demo

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import springfox.documentation.swagger2.annotations.EnableSwagger2

@SpringBootApplication
@EnableSwagger2 // swaggerを有効化するannotaion
class DemoApplication

fun main(args: Array<String>) {
    runApplication<DemoApplication>(*args)
}

브라우저에서 다음 URL로 이동합니다.

다음과 같은 화면이 표시되면 성공입니다. Try it out에서 정상 응답이 반환되는지 확인하십시오.

단, basic-error-controller가 표시되거나 표기가 기본 설정이므로 다음 장에서 수정합니다.

기본값 변경

지정된 끝점 (이번에는 /hello) 만 표시

default Response code/message(예: 401,403,404)를 표시하지 않음

API에 대한 자세한 정보 (설명문이나 버전 등)를 기재한다

DemoApplication.kt

package com.example.demo

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.context.annotation.Bean
import springfox.documentation.builders.ApiInfoBuilder
import springfox.documentation.builders.PathSelectors
import springfox.documentation.service.ApiInfo
import springfox.documentation.spi.DocumentationType
import springfox.documentation.spring.web.plugins.Docket
import springfox.documentation.swagger2.annotations.EnableSwagger2

@SpringBootApplication
@EnableSwagger2
class DemoApplication {

    @Bean
    fun demoApi(): Docket {
        return Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false) // defaultのResponse Code/Messageを表示しない
                .select()
                .paths(PathSelectors.regex("/hello*")) // /hello配下を明示的に選択する
                .build()
                .apiInfo(apiInfo())
    }

    fun apiInfo(): ApiInfo {
        return ApiInfoBuilder()
                .title("API Document Demo")
                .description("This is an API document powered by swagger.")
                .version("0.0.0")
                .build()
    }
}

fun main(args: Array<String>) {
    runApplication<DemoApplication>(*args)
}

HelloController.kt

package com.example.demo.controller

import io.swagger.annotations.ApiOperation
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping
class HelloController {

    @GetMapping("/hello")
    @ApiOperation(value = "Hello Endpoint", notes = "Hello, name!") // ドキュメントに説明文を追加する
    fun hello(@RequestParam(value = "name", required = false, defaultValue = "everyone") name: String): String {
        return "Hello, $name!"
    }
}

구현한 /hello 엔드포인트 문서만 표시되는지 궁금합니다. 또한 설명문도 추가되었습니다. 설명문이 있으면 읽기 쉽고 이해하기 쉬운 API 문서가 되네요.

요약

상상 이상으로 쉽게 API 문서를 생성할 수 있었습니다.

OpenAPI Generator에 의한 API 클라이언트 라이브러리 생성까지 구현하는 것을 목표로 하고 있었습니다만, 집필 시점(2019/05/07) 시점에서는 OAS3.0 미대응이므로, 대응되는 대로, 구현해 보려고 생각합니다.

Springfox의 Open API 3.0에 대한 Issue
htps : // 기주 b. 코 m / sp 린 g 후 x / sp 린 g 후 x / 이스에 s / 2022

OpenAPI Generator
htps : // 기주 b. 코 m / 오나 피토 오 ls / 오 페나 피 네라와 r