[spring boot] swagger 3.0 : OpenAPI 3.0

출처 : kogle.tistory.com/292

 

1. OpenAPI 3.0은 swagger 3.0의 다른 이름이다.

 

2. maven에 단 하나의 라이브러리만 추가하면 된다. 아래 내용만 추가하면 swagger ui도 같이 사용할 수 있다.

 

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

 

3. 기본적인 접근경로는 이전과 동일하다.

  3-1 JSON -> http://localhost:8080/v3/api-docs/ 

  3-2 swagger ui -> http://localhost:8080/swagger-ui.html

 

4. 기본설정

  4-1 OpenAPI 3.0이 되면서 기본설정이 훨씬 간단해 졌다.

    4-1-1 만일 하나의 Docket이 필요한 경우는 아래처럼 application.properties에서 지정할 수 있다.

    4-1-1 이것도 그냥 기본루트가 '/'이고 패키지 전체를 사용할 경우 아예 생략할 수 있다. 즉 config가 없어도 돌아간다.

 

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

 

  4-2 만일 두 개 이상의 문서가 필요한 경우는 아래처럼 예전 방식대로 config 클래스를 지정해야 한다.

    4-2-1 위의 2개의 @Bean이 각 문서를 정의하는 부분이다. v2보다 훨씬 간결하다.

    4-2-2 springShopOpenAPI 함수는 OpenAPI객체를 생성하는데 metaData를 생성해주는 부분이다.

      4-2-2-1 예전의 ApiInfo객체를 생성하는 부분과 유사하다.

 

package pe.pilseong.restdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;

@Configuration

public class SwaggerConfig {

  // @Bean
  // public GroupedOpenApi publicApi() {
  //     return GroupedOpenApi.builder()
  //             .group("springshop-public")
  //             .pathsToMatch("/public/**")
  //             .build();
  // }

  // @Bean
  // public GroupedOpenApi adminApi() {
  //     return GroupedOpenApi.builder()
  //             .group("springshop-admin")
  //             .pathsToMatch("/admin/**")
  //             .build();
  // }

  @Bean
  public OpenAPI springShopOpenAPI() {
      return new OpenAPI()
              .info(new Info().title("SpringShop API")
              .description("Spring shop sample application")
              .version("v0.0.1")
              .license(new License().name("Apache 2.0").url("http://springdoc.org")))
              .externalDocs(new ExternalDocumentation()
              .description("SpringShop Wiki Documentation")
              .url("https://springshop.wiki.github.org/docs"));
  }


  // @Bean
  // public Docket api() {
  //   return new Docket(DocumentationType.OAS_30)
  //     .select()
  //     .apis(RequestHandlerSelectors.any())
  //     .paths(PathSelectors.any())
  //     .build()
  //     .pathMapping("/")
  //     .tags(new Tag("customers", "Swagger Customer Controller"))
  //     .apiInfo(metaData());
  // }

  // private ApiInfo metaData() {
  //   Contact contact = new Contact("Pilseong Heo", "", "heops79@gmail.com");

  //   return new ApiInfo(
  //     "Spring REST demo", 
  //     "Spring Boot REST Demo", 
  //     "1.0", 
  //     "Terms of Service",
  //     contact, 
  //     "Nothing", 
  //     "No limitation", 
  //     new ArrayList<>());
  // }
}

5. v2와 달라진 annotation들

• @Api -> @Tag
• @ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
• @ApiImplicitParam -> @Parameter
• @ApiImplicitParams -> @Parameters
• @ApiModel -> @Schema
• @ApiModelProperty(hidden = true) -> @Schema(accessMode = READ_ONLY)
• @ApiModelProperty -> @Schema
• @ApiOperation(value = "foo", notes = "bar") -> @Operation(summary = "foo", description = "bar")
• @ApiParam -> @Parameter
• @ApiResponse(code = 404, message = "foo") -> @ApiResponse(responseCode = "404", description = "foo")

 

 

1. api 그룹 설정 : @Tag

Target : ANNOTATION_TYPE, METHOD, TYPE

• name : 태그의 이름
• description : 태그에 대한 설명

 

Tag에 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶습니다.
주로 Controller Class 나 Controller Method 영역에 설정합니다.

import io.swagger.v3.oas.annotations.tags.Tag; @Tag(name = "user", description = "사용자 API") @RequestMapping(value = "${demo.api}/users") @RestController public class UserController { ... }

UserController 에 @Tag를 설정해 보았습니다.

 

 

 

@Tag 애너테이션 설정을 완료한 후 Swagger UI 화면입니다.
태그명과 설명이 각 태그에 설정되었습니다.

---

2. api Schema 설정 : @Schema

Target : ANNOTATION_TYPE, FIELD, METHOD, PARAMETER, TYPE

• description : 한글명
• defaultValue : 기본값
• allowableValues :

 

Schmea(= Model)에 대한 정보를 작성하는 곳입니다.
Schema를 설정할 시, 더욱 완성도 높은 Swagger UI 문서를 만들 수 있습니다.

 

@Schema 설정을 하지 않은 UserValue 모델 정보입니다.
각 필드값들에대한 설명이나 기본값, 허용가능한 값 등에 대한 정보 없이 string 요소가 들아간다는 말뿐이라 어떤 값이 들어가는지 모호합니다.

 

출처: https://blog.jiniworld.me/91 [hello jiniworld]