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

У меня есть API ReSTFul, написанный на простом Spring (без Spring Boot, без всяких причуд!). Мне нужно внедрить в это Swagger. До сих пор КАЖДАЯ страница в Интернете сводила меня с ума запутанными конфигурациями и раздутым кодом, который я вообще не считал переносимым.

Есть ли у кого-нибудь образец проекта (или набор подробных шагов), который может помочь мне в этом? В частности, я ищу хороший образец, использующий swagger-springmvc. Я знаю, что в нем есть «образцы», но в лучшем случае эзотерический код обескураживает.

Я должен пояснить, что я не ищу, «почему Swagger просто лучший». Я не использую (и для моей текущей задачи не буду использовать) Spring Boot или что-то подобное.

Springfox (Swagger spec 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 использует Джексона для привязки данных.

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

<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, то, как упоминает 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 spec 1.2, старше)

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

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

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

@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="/" />

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

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

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

Пользовательский интерфейс Springfox Swagger у меня работает после добавления зависимостей WebJar и сопоставлений ресурсов. http://www.webjars.org/documentation#springmvc

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.3.5</version>
    </dependency>

Spring-servlet.xml:

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

или Spring Annotation https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java

Swagger2 должен быть включен

 @EnableSwagger2
 public class SwaggerConfiguration {
 }

Вы также можете использовать swagger-maven-plugin для создания swagger.json и скопировать его в свой статический swagger-ui.

Пожалуйста, проверьте простой образец рабочего плагина с аннотациями Spring MVC в этом репо:

https://github.com/khipis/swagger-maven-example

или для JAX-RS

https://github.com/kongchen/swagger-maven-example