🛠️ Swagger ?

API 문서에 대해 고민한 적이 있다. 이유는 API 문서를 노션에 관리해서 소비자에게 전달했는데, 정말 귀찮은 프로세스였다.

 

개발 - 테스트 - API Notion 최신화 - 수정 - 개발 - 테스트 - API Notion 최신화

 

아니 다른 방법이 있다. 찾고 적용하자라는 마인드로 REST Docs 찾아서, 적용한 적이 있다.

 

이때 고생 아닌 고생을 해야 했는데, 우선 모든 API에 대해 테스트 코드를 다시 작성했다. 

UI를 위해 Asciidoctor인가? 문법을 보면서 template를 작성했다. 설정도 복잡했고,  가장 중요한 건 코드 작업량이 미쳤다는 것이다.

 

테스트 코드도 유지보수의 작업인데, 이게 혼자 백엔드를 개발하는데 감당이 안된다.  

같이하면 뭐.. 그래도 마무리했다..

 

이번 팀프로젝트에서 API 문서로 Swagger를 사용하기로 했다. 난 사용 안 해봐서 간단히 정리해 본다.

 

 

🛠️ Swagger

---

Swagger는 API 개발을 위한 도구로, API의 디자인, 문서화, 테스트 및 사용 가능한 클라이언트 SDK를

자동으로 생성하는 오픈 소스 소프트웨어 프레임워크입니다.

 

Swagger는 API를 설계할 때 사용되는 명세 문서를 작성하기 위한 형식인 OpenAPI Specification (OAS)를 사용합니다.

 

Swagger를 사용하면 개발자는 API의 엔드포인트 (Endpoints), 매개변수 (Parameters), 응답 형식 (Response Formats) 및 인증 방법 등을 정의할 수 있습니다.

 

이러한 정보들은 Swagger UI를 통해 시각적으로 표현되며, 사용자는 Swagger UI를 통해 API의 작동 방식을 이해하고 테스트할 수 있습니다.

 

Swagger는 API 개발자와 소비자 간의 협업을 강화하고, 개발 프로세스를 단순화하며, 문서화 작업을

자동화하여 개발자들이 보다 쉽게 API를 사용하고 구축할 수 있도록 도와줍니다.

 

OpenAPI Specification

---

[OpenAPI Sepcification]

 

OpenAPI Spec은 2015년 Open Initiative에 따라 Linux Foundation에 기부되었습니다.

 

이 사양은 API와 관련된 모든 리소스 및 작업을 효과적으로 매핑하여 API를 쉽게 개발하고 사용하기

위한 RESTful 인터페이스를 생성합니다.

 

What?

HTTP API에 대한 프로그래밍 언어에 구애받지 않은 표준 인터페이스

 

Version

가끔씩 마이너 버전에서 비호환성 있는 변경이 발생할 수 있다. 이는 변경이 제공되는 이점에 비해 영향이 상대적으로 낮을 때 이루어진다.

 

Format

OpenAPI 사양을 준수하는 OpenAPI 문서는 그 자체로 JSON 또는 YAML 형식으로 표시될 수 있는

JSON 개체이다.

( YAML과 JSON 형식 간 변환 기능을 유지하기 위해 YAML version 1.2를 권장)

 

참고: API는 OpenAPI 문서에서 YAML 또는 JSON 형식으로 정의할 수 있지만 API 요청 및 응답 본문과 기타 콘텐츠는 JSON 또는 YAML일 필요가 없습니다.

 

 

OpenAPI 라이브러리를 사용하면 프로그래밍 방식으로 API 문서에 필요한 요소를 작성할 수 있고,

이를 기반으로 OpenAPI 명세에 맞는 JSON 또는 YAML 파일을 생성해 준다라고 정리

 

추가적으로 이를 통해 자동으로 API 문서를 생성하거나, Swagger UI와 같은 시각적 인터페이스를 제공하여 테스트할 수도 있다.

 

Spring-boot v3, Swagger Settings

---

springdoc-openapi v2.1.0

 

소개

springdoc-openapi 자바 라이브러리는 스프링 부트 프로젝트를 사용하여 API 문서 생성을 자동화하는 데

도움이 되며, 런타임에 애플리케이션을 검사하여 스프링 구성, 클래스 구조 및 다양한 어노테이션을 기반으로 API 시맨틱을 추론하는 방식으로 작동.

 

해당 버전의 springdoc-openapi v2.1.0은 다음을 지원합니다.

• OpenAPI 3
• Spring-boot v3 ( Java 17 & Jakarta EE 9)
• JSR-303
• Swagger-ui
• OAuth 2

설정 시작

 

1. spring-boot와 swagger-ui 간의 통합을 위해 라이브러리를 종속성 추가.

// <https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui/2.1.0>
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0")

Gradle(Kotiln)

 

자동으로 spring-boot 애플리케이션에 배포됩니다.

 

The Swagger UI page will then be available at http://server:port/context-path/swagger-ui.html

 

and the OpenAPI description will be available at the following url for json

 

format: http://server:port/context-path/v3/api-docs

 

💡 # swagger-ui custom path springdoc.swagger-ui.path=/swagger-ui.html

 

 

2. Kotlin

In addition, your project should add jackson-module-kotlin as well to have the full support of Kotlin types

//kotlin
implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
implementation("org.jetbrains.kotlin:kotlin-reflect")

 

3. Swagger-UI 공식 속성 설정

라이브러리는 swagger-ui 공식 속성을 지원합니다.

• https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/

Swagger Documentation

swagger-ui 속성을 spring-boot 속성으로 선언해야 합니다. 이러한 모든 속성은 springdoc.swagger-ui 접두사를 사용하여 선언해야 합니다.

 

5. Selecting the Rest Controllers

 

Additionally, to @Hidden annotation from swagger-annotations, its possible to restrict the generated OpenAPI description using package or path configuration.

 

For the list of packages to include, use the following property:

# Packages to include springdoc.packagesToScan=com.package1, com.package2

 

For the list of paths to include, use the following property:

# Paths to include springdoc.pathsToMatch=/v1, /api/balance/**

 

 

5.1 Springdoc-openapi 핵심 속성

https://springdoc.org/#springdoc-openapi-core-properties

OpenAPI 3 Library for spring-boot

 

5.2 swagger-ui 속성

https://springdoc.org/#swagger-ui-properties

OpenAPI 3 Library for spring-boot

 

 

개발환경 설정

---

 

알려진 경로는 보안상 취약할 수 있습니다. endpoint path를 수정합니다.

# Disabling the /v3/api-docs endpoint
springdoc:
  api-docs:
    path: /path/docs

 

 

 

별다른 설정을 하지 않아도 @RestController 어노테이션을 인식하는 것 같습니다.

 

여기서 무엇을 발전시켜야 할까요? 실무에서는 어떻게 더 진행할까요?

 

 

이럴 땐 기술 블로그를 참고해야 합니다.

 

 

tren:be 마이크로 서비스 환경에서 통합된 API 문서 서버 구축하기

마이크로 서비스 환경에서 통합된 API 문서 서버 구축하기 - 트렌비 기술블로그

 

kakaopay, OAS 이용한 더욱 효과적인 API 문서화

OpenAPI Specification을 이용한 더욱 효과적인 API 문서화 | 카카오페이 기술 블로그

 

Kurly 내가 만든 API를 널리 알리기

내가 만든 API를 널리 알리기 - Spring REST Docs 가이드편

 

대부분 장점을 취해 사용하려고 하고, 대규모 팀에 대해 개발 서버에 대한 배포만을 진행하는군요.

MSA 환경에서 API 문서 서버 만들기도 하고요. 

 

글의 이미지를 보면서 어떤 부분을 개선해서 사용하는지 살펴보았습니다. 찾기 힘들군요.

 

개인적으로는 다음과 같이 설명이 추가되었으면 합니다.

 

@Target(value={TYPE,PACKAGE})
 @Retention(value=RUNTIME)
 @Inherited
public @interface OpenAPIDefinition
The annotation that may be used to populate OpenAPI Object fields info, tags, servers, security and externalDocs
If more than one class is annotated with OpenAPIDefinition, with the same fields defined, behaviour is inconsistent.

 

다음 코드를 통해 버전, 제목, 설명 및 OAS JSON 파일 링크까지 해결했습니다.

@OpenAPIDefinition(info = @Info(
        title = "Project API",
        version = "1.0",
        description = "Documentation Project API v1.0")
)

 

이제 저 흉물스러운 login-controller 이름 및 경로에 설정을 진행합니다.

@Tag(name = "Login")
@RestController
@RequestMapping("/login")
class LoginController(
		private val loginService: LoginService
) {
	@Operation(summary = "Login")
	@ApiResponse(
			responseCode = "200",
			description = "Login",
			content = [Content(
					mediaType = "application/json",
					schema = Schema(implementation = String::class)
			)]
	)
	@PostMapping("/")
	fun login(
			@RequestBody request:String,
			@RequestBody salt:String
	) {
		...
	}
}

 

이제 지속적으로 발전해 나가면 될 것 같습니다.

 

근데 swagger의 어노테이션 하위 객체들에 대한 설명이 javadoc에만 있고, 필드 설명이 잘 안 되어 있어 찾아

보기 무척 힘들었습니다..

 

 

 

 

https://docs.swagger.io/swagger-core/v2.0.0-RC3/apidocs/io/swagger/v3/oas/annotations/package-summary.html

https://springdoc.org/#Introduction

https://spec.openapis.org/oas/v3.1.0