"Простой" способ реализации Swagger в приложении Spring MVC

Springfox (Swagger spec 2.0, current)

Springfox заменил Форс-инфраструктуре springmvc, и теперь поддерживает как чванство технические характеристики 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();
    }

}

ваша документация по API Swagger 2.0 теперь будет доступна по адресу http://myapp/v2/api-docs.

Примечание: Если вы не используете Spring boot, то вы должны добавить зависимость jackson-databind. Поскольку springfox использует Джексона для привязки данных.

добавление чванство поддержка пользовательского интерфейса теперь еще проще. Если вы используете Maven, добавьте следующую зависимость для веб-интерфейса Swagger UI:

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

если вы используете Spring Boot, то ваше веб-приложение должно автоматически подобрать необходимые файлы и показать пользовательский интерфейс в http://myapp/swagger-ui.html (ранее: http://myapp/springfox). Если вы не используете Spring Boot, то, как упоминает Юрий-тумаха в ответе ниже, вам нужно будет зарегистрировать обработчик ресурсов для файлов. Конфигурация 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/");
    }

}

в новый генерация статической документации функция также выглядит довольно приятно, хотя я не пробовал его сам.

Форс-инфраструктуре springmvc (чванство спецификации 1.2, старше)

документация Swagger-SpringMVC может быть немного запутанным, но на самом деле невероятно легко настроить. Самая простая конфигурация требует создания SpringSwaggerConfig bean и включение конфигурации на основе аннотаций (что вы, вероятно, уже делаете в своем Spring MVC проект):

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

тем не менее, я думаю, что стоит сделать дополнительный шаг по определению пользовательской конфигурации Swagger с помощью SwaggerSpringMvcPlugin, вместо предыдущего XML-определенного компонента:

@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, вам нужно клонировать статические файлы из проект GitHub и положил их в свой проект. Убедитесь, что ваш проект настроено для обслуживания статических HTML файлов:

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

затем измените на верхнем уровне пользовательского интерфейса чванство . В верхней части файла вы увидите некоторый JavaScript, который ссылается на api-docs URL другого проекта. Отредактируйте это, чтобы указать на документацию Swagger вашего проекта:

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

теперь, когда вы выберите http://myapp/path/to/swagger/index.html, вы должны увидеть экземпляр пользовательского интерфейса чванство для вашего проекта.