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

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

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

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

ОТВЕТЫ

Ответ 1

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();
    }

}

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

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

Добавлена поддержка Swagger UI. Если вы используете 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/");
    }

}

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

Swagger-SpringMVC (Swagger spec 1.2, старше)

Документация для Swagger-SpringMVC может быть немного запутанной, но на самом деле ее невероятно легко настроить. Самая простая конфигурация требует создания SpringSwaggerConfig компонента SpringSwaggerConfig и включения конфигурации на основе аннотаций (что вы, вероятно, уже делаете в своем проекте 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="/" />

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

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

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

Ответ 2

Интерфейс 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 Аннотация https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java

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

 @EnableSwagger2
 public class SwaggerConfiguration {
 }

Ответ 3

Вы также можете использовать 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