Swagger 설정 - tjdwns4537/mybatis-practice GitHub Wiki

Swagger 설정 코드


    1. YAML 설정방법: 설정 파일을 수정하면 서버 재시작 없이 변경 사항이 적용되므로, 런타임에서 설정 변경이 용이합니다. 그리고 설정이 파일로 분리되므로, 코드와 설정이 분리되어 관리하기 쉽습니다.
    1. Annotation 설정방법: 간단한 설정이나 작은 프로젝트에서는 빠르게 설정할 수 있으며, Swagger 관련 설정이 코드 내에 분산되어 있습니다. 설정 변경 시 코드를 수정해야 하므로, 변경 시 재배포가 필요합니다.

implementation group: 'io.springfox', name: 'springfox-swagger2', version: '3.0.0'
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
  • springboot/swagger version 호환성을 맞춰야함

@OpenAPIDefinition(
    info = @Info(
        title = "spring commerce API 명세서",
        description = "API 명세서",
        version = "v1",
        contact = @Contact(
            name = "beginners",
            email = "[email protected]"
        )
    )
)
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30) // 3.0 문서버전으로 세팅
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mybatistest.member.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger 3.0 Api Sample")
                .description("This is Sample")
                .version("1.0")
                .build();
    }
}

코드 설명

  • @OpenAPIDefinition: 명세 전체에 대한 공통 설명 ( OpenAPI 3.0 스펙을 정의하는 데 사용되는 어노테이션 )

  • apiInfo(): Swagger API문서에 대한 설명을 표기 (선택) (Swagger와 Spring Boot 프로젝트를 통합하고 API 문서를 생성하기 위한 것)

  • @EnableSwagger2: 스웨거 활성화

  • Docket: Swagger 설정을 도와주는 클래스

  • groupName(): Docker Bean 충돌 방지를 위함

  • consume(), produces()는 각각 Request Content-Type, Response Content-Type에 대한 설정 (선택)

  • select(): ApiSelectorBuilder를 생성해 apis()와 paths()를 사용할 수 있게 해줌

  • apis(): Swagger API문서로 만들기 원하는 Base Package 경로 (필수)

  • path(): URL경로를 지정해 해당 URL에 해당하는 요청만 Swagger API 문서로 만듬 (필수)

  • useDefaultResponseMessages(): false로 설정하면 swagger에서 제공해주는 응답코드에 대한 기본 메시지를 제거해줌 (200,401,403,404)


Controller 작성 코드

  • @Operation(summary="메소드 요약 정보", description="result 정보", tags={""})
  • @ApiOperation(value="API명세")

사용하지 않은 기능

  • GroupedOpenApi: 그룹 설정된 api들만 문서에 노출시킬 수 있게 해줍니다. (프로젝트가 충분히 크다면 API분류를 통해 스펙을 다양하게 문서화 할 수 있다는 장점을 지님)
@Bean
public GroupedOpenApi getApi(){
    ...
}

yml 파일


springdoc:
  swagger-ui:
    path: /swagger-ui.html
    groups-order: DESC
    operationsSorter: method
    disable-swagger-default-url: true
    display-request-duration: true
  api-docs:
    path: /api-docs
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  paths-to-match:
    - /v1/**
  • swagger-ui.path: HTML형식의 Swagger 문서 사용자 경로(default: /swagger-ui.html)
  • api-docs.path: Json형식의 OpenAPI 설명서 사용자 정의 경로
  • disable-swagger-default-url: petstore html(swagger-ui default url)문서 비활성화 여부(true/false)
  • group-order: 그룹 정렬 기준 (DESC/ASC)
  • operation-sorter: 컨트롤러 내에서 정의한 api 메서드 순서(alpha: 알파벳 오름차순, method: HTTP method순)
  • display-request-duration: try it out 했을 때, request duration을 추가로 찍음(true/false)
  • cache.disabled: swagger cache 설정(true/false)

Swagger 사용하기

⚠️ **GitHub.com Fallback** ⚠️