📑 Swagger – API 문서 자동화하기

혼자 개발할 때에는 그냥 만들면 되지만, 협업 시에는 API 문서를 업데이트하는 것이 꽤나 신경 쓰이는 일이다. 공유 클라우드나 플랫폼(notion, confluence 등)을 활용하는 것도 좋은 방법이지만 더 쉽게 만들 수 있는 방법이 있다! 물론 난 공유 문서에 작성해두고, Swagger도 사용한다. 각각의 방식에는 장단점이 있기 때문이다.

🤔 Swagger?

REST web service를 설계, 빌드, 문서화 등의 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈소스 소프트웨어 프레임 워크

• API 정보 자동 갱신
• API를 통해 파라미터, 응답, 정보, 예시 등 spec 정보 전달에 용이
• 실제 사용 되는 파라미터로 테스트를 할 수 있는 기능 지원
• Java에 종속된 라이브러리가 아니기 때문에 다른 언어로 개발된 웹 프레임워크에서 동일하게 구성 가능
• FE와 BE 간의 개발 진행 상황 및 편리한 API 세부 사항 공유 가능

Swagger가 지원하는 기능

• API Design
  • Swagger-editor를 통해 API를 문서화하고 빠르게 명세 작성 가능
• API Development
  • Swagger-codepen을 통해 작성된 문서의 SDK를 생성 → 빌드 프로세스 간소화
• API Documentation
• API Testing
  • Swagger-Inspector를 통해 API 시각화 및 빠른 테스팅 가능
• Standardize
  • Swagger-hub를 통해 개인, 팀원들이 API 정보를 공유

🧭 환경 설정

springfox-boot-starter 사용 시 Spring Boot 2.5.x 버전 이후부터는 Spring과 Swagger 간의 버전 호환이 되지 않아 오류 발생 → Spring Boot 2.4.x 버전으로 낮춰서 해결 필요
참고 : Spring Boot 2.6.2에 Swagger 적용 시 오류, SpringBoot 2.6에서 swagger 3.0 사용

이 글에서는 springfox 대신 springdoc을 사용한다.

Gradle

dependencies {
	...
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
	...
}

Maven

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

application.yml

springdoc:
	api-docs:
		path: /api-docs
		group:
			enable: true
	swagger-ui:
		path: /swagger-ui-custom.html
		enabled: true
		groups-order: ASC
		tags-sorter: alpha
		operations-sorter: alpha
		display-request-duration: true
		doc-expansion: none
	cache:
		disabled: true
	model-and-view-allowed: true

SwaggerConfig.java

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

	@Bean
    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> {
            this.addResponseBodyWrapperSchemaExample(operation);
            return operation;
        };
    }

    private void addResponseBodyWrapperSchemaExample(Operation operation) {
        final Content content = operation.getResponses().get("200").getContent();
        if (content != null) {
            content.forEach((mediaTypeKey, mediaType) -> {
                Schema<?> originalSchema = mediaType.getSchema();
                Schema<?> wrapperSchema = wrapSchema(originalSchema);
                mediaType.setSchema(wrapperSchema);
            });
        }
    }

    private Schema<?> wrapSchema(Schema<?> originalSchema) {
        Schema<?> wrapperSchema = new Schema<>();
        wrapperSchema.addProperties("status", new Schema<>().type("integer").example(200));
        wrapperSchema.addProperties("message", new Schema<>().type("string"));
        wrapperSchema.addProperties("data", originalSchema);
        return wrapperSchema;
    }

    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .version("v1.0.0")
                .title("API")
                .description("");

        SecurityScheme auth = new SecurityScheme()
                .type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.COOKIE).name("JSESSIONID");
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("sessionAuth"); // 헤더에 토큰 포함

        // When Using JWT, Activate Below Code
//  	String jwt = "JWT";
//  	SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwt); // 헤더에 토큰 포함
//  	Components components = new Components().addSecuritySchemes(jwt, new SecurityScheme()
//   		.name(jwt)
//   		.type(SecurityScheme.Type.HTTP)
//   		.scheme("Bearer")
//   		.bearerFormat("JWT")
//  	);

        return new OpenAPI()
                .addServersItem(new Server().url("/"))
                .info(info)
                .addSecurityItem(securityRequirement)
                .components(new Components().addSecuritySchemes("sessionAuth", auth))
                ;

    }

}

🚀 How to use

Controller

@RestController
@RequiredArgsConstructor
@RequestMapping("example")
@Tag(name = "예시 컨트롤러")
public class ExampleController {

    private final ExampleService exampleService;

    @GetMapping("{exampleId}")
    @Operation(summary = "예시 조회", description = "예시를 조회합니다.")
    @ApiResponse(responseCode = "200", description = "성공", content = @Content(schema = @Schema(implementation = ExampleResponseDto.class)))
    public Response<?> exampleMethod(@RequestBody ExampleRequestDto exampleRequestDto, @PathVariable Long exampleId) {
        return Response.ok(exampleService.exampleMethod(exampleRequestDto), "성공적으로 예시를 반환하였습니다.");
    }
}

DTO

DTO class에서는 request를 위한 example value를 설정할 수 있다. 미리 작성해서 전달해두면 동작 테스트 시 편하기 때문에 권장한다.

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class ExampleRequestDto {

    @Schema(description = "예시 ID", example = "1")
    private Long exampleId;

    @Schema(description = "예시 제목", example = "title")
    private String exampleTitle;
}

DTO 클래스는 물론 DTO 클래스에서 사용하는 다른 클래스 내부에도 @Schema annotation을 활용하면 동일하게 설정할 수 있다.

Swagger annotation

annotation	description
@Api	클래스를 스웨거의 리소스로 표시 • 해당 클래스가 Swagger 리소스라는 것을 명시 • 클래스 위에 선언
@ApiOperation	특정 경로의 operation HTTP method 설명 • 한 개의 Operation을 선언 • 메소드 위에 선언
@ApiParam	operation parameter에 메타 데이터 설명 • 파라미터에 대한 정보 명시 • method 안에, 파라미터 위에 선언
@ApiResponse	operation의 응답 지정
@ApiModelProperty	모델의 속성 데이터를 설명 • Dto class 안의 property 위에 선언
@ApiImplicitParam	method 단위의 operation parameter 설명 • 파라미터에 대한 정보 명시 • method 위에 선언
@ApiImplicitParams	method 단위의 operation parameter 여러 개 설명 • 파라미터에 대한 정보 명시 • method 위에 선언

SwaggerConfig class method

method	description
useDefaultResponseMessages()	false : Swagger에서 제공하는 응답 코드 (200, 401, 403, 404)에 대한 기본 메세지 제거
groupName()	Docket Bean이 한 개일 경우 생략 가능, 둘 이상일 경우 충돌 방지를 위해 설정
select()	• ApiSelectorBuilder를 생성 • apis()와 paths()를 사용할 수 있게 해줌
apis()	• api spec이 작성되어 있는 패키지 지정 • 컨트롤러가 존재하는 패키지를 base package로 지정 -> 해당 패키지에 존재하는 API 문서화 • RequestHandlerSelectors.any() : 모든 패키지를 base package로 지정해 API 문서화
paths()	• apis()로 선택되어진 API 중 특정 path 조건에 맞는 API들을 다시 필터링 -> 문서화 • PathSelectors.any()로 설정하면 패키지 안에 모든 API를 한 번에 볼 수 있음
apiInfo()	제목, 설명 등 문서에 대한 정보들을 설정하기 위해 호출

Execute

1. application을 실행한다.
2. 아래 url 중 하나에 접속한다.
   • http://localhost:8080/swagger-ui/index.html
   • http://localhost:8080/swagger-ui-custom.html
3. Swagger-UI 화면을 볼 수 있다.
4. 사용자 API를 클릭하면 상세 API 목록을 볼 수 있다.
   

---

Reference : Swagger 공식 문서, springdoc-openapi repository, springdoc.org, Baeldung OpenAPI 3.0 문서