출처1 : https://springdoc.org/

출처2 : https://github.com/springdoc/springdoc-openapi

출처3 : https://github.com/springdoc/springdoc-openapi-demos

출처4 : https://stackoverflow.com/questions/70855605/how-to-ask-swagger-ui-to-add-bearer-token-field-for-each-endpoint-globally

출처5 : https://springdoc.org/faq.html

출처6 : https://www.baeldung.com/spring-rest-openapi-documentation

출처7 : https://wookim789.tistory.com/56

환경 - spring boot 2.6.x

pom.xml 만 가지고 활성화가 가능하다.

기본 적으로 아래 주소로 UI를 확인할 수 있다.

http://localhost:8081/swagger-ui/index.html

pom.xml

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.6</version>
</dependency>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-data-rest</artifactId>
    <version>1.6.6</version>
</dependency>

다만 spring security 설정이 되어 있다면 아래와 같이 허용해주자.

.antMatchers("/v3/api-docs/**", "/swagger-ui.html", "/swagger-ui/**").permitAll()

추가적으로 ui에서 인증이 필요한 부분이 있을텐데 아래와 같이 해결 할 수 있다.

아래 @Bean이 두 개가 설정되어 있는데,

주석을 확인하고 하나만 설정하도록 하자.

SpringDocConfig.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 org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Arrays;
import java.util.Collections;

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        // https://springdoc.org/faq.html
        // 함수별로 지정할 수 있다.
        // 단 함수의 @Operation 에 아래와 같이 추가해줘야 한다.
        // @Operation(summary = "함수 설명입니다.", security = {@SecurityRequirement(name = "bearer-key")})
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("bearer-key",
                                new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
    }

    @Bean
    public OpenAPI customOpenAPI() {
        // https://stackoverflow.com/questions/70855605/how-to-ask-swagger-ui-to-add-bearer-token-field-for-each-endpoint-globally
        // 전역으로 할 수 있는 자물쇠를 사용한다
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("bearer-key",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")
                        )
                )
                .info(new Info()
                        .title("Auth Service API")
                        .description("Documentation of API v.1.0")
                        .version("1.0")
                ).addSecurityItem(
                        new SecurityRequirement()
                                .addList("bearer-jwt", Arrays.asList("read", "write"))
                                .addList("bearer-key", Collections.emptyList())
                );
    }
}

문법 샘플 (단일 리턴)

@Tag(name = "컨트롤러 이름", description = "컨트롤러의 설명")
@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/auth/sc-test")
public class TestController {

    private final UserService userService;

    @Operation(summary = "함수 설명입니다.", security = {@SecurityRequirement(name = "bearer-key")})

    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "정상으로 찾으면 아래처럼 리턴한다",
                    content = {@Content(mediaType = "application/json", schema = @Schema(implementation = GetUserInfoDto.class))}
            ),
            @ApiResponse(responseCode = "400", description = "Invalid id supplied", content = @Content),
            @ApiResponse(responseCode = "404", description = "Book not found", content = @Content)
    })
    @GetMapping("/{id}")
    public GetUserInfoDto findById(
            @Parameter(example = "11EC8FB7C32BA4FAAE8202915ECBC9E4", description = "id of book to be searched") @PathVariable String id) {
        return userService.getUserInfo(id);
    }
}

문법 샘플 (리스트 리턴)

@Operation(summary = "이전 채팅내용 가져오기", security = {@SecurityRequirement(name = "bearer-key")})
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "프론트에서 가지고 있는 가장 이전 메시지의 ID를 넘기면 그걸 기준으로 위로 100개씩 가져온다.",
                content = {@Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = ChatMessage.class)))}
        ),
})
@GetMapping("/{sessionId}/history/{messageId}")
public ResponseEntity getHistory(@PathVariable String sessionId, @PathVariable String messageId, @RequestParam(defaultValue = "100") int size) {
    return ResponseEntity
            .status(HttpStatus.OK)
            .body(chatService.findChatMessageHistoryById(sessionId, messageId, size));
}

[SpringDoc] SpringDoc을 사용한 OpenAPI 문서화 feat.swagger