[spring] Spring MVC 애플리케이션에서 Swagger를 구현하는 ‘간단한’방법

Springfox (Swagger 사양 2.0, 현재)

Springfox 는 Swagger-SpringMVC를 대체했으며 이제 Swagger 사양 1.2 및 2.0을 모두 지원합니다. 구현 클래스가 변경되어 더 심층적 인 사용자 정의가 가능하지만 일부 작업이 필요합니다. 문서 개선,하지만 여전히 고급 구성을 위해 추가 된 몇 가지 세부 사항을해야합니다. 1.2 구현에 대한 이전 답변은 여전히 ​​아래에서 찾을 수 있습니다.

Maven 종속성

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>

최소한의 구현은 거의 비슷해 보이지만 이제는 Docket클래스 대신 클래스를 사용합니다 SwaggerSpringMvcPlugin.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

Swagger 2.0 API 문서는 이제 http://myapp/v2/api-docs.

참고 : Spring 부트를 사용하지 않는 경우 jackson-databind 종속성을 추가해야합니다. springfox는 데이터 바인딩에 jackson을 사용하기 때문에.

이제 Swagger UI 지원을 추가하는 것이 훨씬 더 쉽습니다. Maven을 사용하는 경우 Swagger UI webjar에 다음 종속성을 추가하십시오.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

Spring Boot를 사용하는 경우 웹 앱이 자동으로 필요한 파일을 선택하고 http://myapp/swagger-ui.html(이전 :)에 UI를 표시해야합니다 http://myapp/springfox. Spring Boot를 사용하지 않는 경우 yuriy-tumakha가 아래 답변에서 언급했듯이 파일에 대한 리소스 핸들러를 등록해야합니다. Java 구성은 다음과 같습니다.

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

새로운 정적 문서 생성 기능도 꽤 멋져 보이지만 직접 시도하지는 않았습니다.

Swagger-SpringMVC (Swagger 사양 1.2 이전)

Swagger-SpringMVC에 대한 문서는 약간 혼란 스러울 수 있지만 실제로 설정하는 것은 매우 쉽습니다. 가장 간단한 구성은 SpringSwaggerConfig빈을 생성하고 주석 기반 구성을 활성화 해야 합니다 (아마도 Spring MVC 프로젝트에서 이미 수행 한 작업).

<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

그러나 SwaggerSpringMvcPlugin이전 XML 정의 빈 대신을 사용하여 사용자 지정 Swagger 구성을 정의하는 추가 단계를 수행하는 것이 좋습니다.

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    @SuppressWarnings("SpringJavaAutowiringInspection")
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*api.*"); // assuming the API lives at something like http://myapp/api
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

애플리케이션을 실행할 때 이제에서 생성 된 API 사양을 볼 수 있습니다 http://myapp/api-docs. 멋진 Swagger UI를 설정하려면 GitHub 프로젝트 에서 정적 파일을 복제하여 프로젝트 에 넣어야합니다. 프로젝트가 정적 HTML 파일을 제공하도록 구성되었는지 확인합니다.

<mvc:resources mapping="*.html" location="/" />

그런 다음 index.htmlSwagger UI dist디렉터리 의 최상위 수준에서 파일을 편집합니다 . 파일 상단 api-docs에는 다른 프로젝트 의 URL을 참조하는 JavaScript가 있습니다. 프로젝트의 Swagger 문서를 가리 키도록 편집하십시오.

  if (url && url.length > 1) {
    url = url[1];
  } else {
    url = "http://myapp/api-docs";
  }

이제로 이동하면 http://myapp/path/to/swagger/index.html프로젝트에 대한 Swagger UI 인스턴스가 표시됩니다.