Open Api Specification의 약자로, RESTful API 디자인에 대한 명세 표준이다.
OpenAPI Specification는 본래 Swagger Specification라는 이름으로 불렸었다. (그래서 이전버전에선 Swagger 2.0이라고 칭함) 허나 기술 소유주가 전환되는 과정에서 이름이 바뀌었다.
허나 Swagger라는 용어도 계속 사용하고 있기 때문에 OAS랑 Swagger 용어에 대해 헷갈리곤 하는데 간단히 정리하자면
보통 json이나 yaml로 API 스펙을 정의하게 되고, Swagger-ui로 문서를 시각화할 수 있다.
현재 3.0 버전까지 나왔다.
사용 예시
paths:
/users/{userId}:
get:
summary: Get a user by ID
parameters:
...
responses:
'200':
description: A single user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/users:
get:
summary: Get all users
responses:
'200':
description: A list of users.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
앞서 이에 대한 고민을 한 사람들이 있고, 그들이 제공하는 자동화 라이브러리가 몇가지 있다.
Spring REST Docs는 ****실제 테스트 코드를 API 문서로 생성한다.
만들어진 문서의 형식은 .adoc 스니펫 파일로서, gradle 플러그인을 사용해 Asciidoctor를 실행해야 html, pdf 등의 형식으로 변환이 가능하다.
허나 만약 .adoc 문서를 OAS Swagger-Ui로 시각화하기 위해선 OAS에 맞게 직접 (수동으로) json 혹은 yaml 형식으로의 수정이 불가피하다. 상당히 번거롭고 일을 두번하게 되는 셈이다.
다행인 건 이를 지원하는 라이브러리가 있다는 것이고, 그게 바로 restdocs-api-spec 이다.
세팅 방법
buildscript {
ext {
restdocsApiSpecVersion = "0.17.1" // restdocsApiSpecVersion 버전 변수 설정
}
}
plugins {
id("com.epages.restdocs-api-spec"") version "${restdocsApiSpecVersion}"
}
dependencies {
.
.
.
// restdocs-api-spec 의존성 추가 (spring rest docs 의존성 포함하고 있음)
testImplementation("com.epages:restdocs-api-spec-mockmvc:$restdocsApiSpecVersion")
}
bootJar{
dependsOn(':openapi3')
}
openapi3 {
server = "<http://localhost:8081>"
title = "restdocs-swagger Test API Documentation"
description = "Spring REST Docs with SwaggerUI"
version = "0.0.1-SNAPSHOT"
format = "json"
outputDirectory = "src/main/resources/static"
outputFileNamePrefix = "swagger
}