"Простой" способ реализации Swagger в приложении Spring MVC
У меня есть API-интерфейс ReSTFul, написанный на простом Spring (без Spring Boot, без всяких причуд!). Мне нужно внедрить Swagger в это. До сих пор КАЖДАЯ страница в Интернете сводила меня с ума только из-за запутанных конфигураций и раздутого кода, который я вообще не нашел переносимым.
У кого-нибудь есть пример проекта (или набор подробных шагов), который может помочь мне в этом? В частности, я ищу хороший образец, который использует swagger-springmvc. Я знаю, что у него есть "образцы", но в лучшем случае эзотерический код разочаровывает.
Я должен уточнить, что я не ищу "почему Swagger просто лучший". Я не использую (и для моей текущей задачи не буду использовать) Spring Boot или что-то подобное.
3 ответа
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 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="/" />
Затем отредактируйте index.html файл на верхнем уровне Swagger UI dist каталог. В верхней части файла вы увидите 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, вы должны увидеть экземпляр Swagger UI для вашего проекта.
Springfox Swagger UI работает для меня после добавления зависимости WebJar и сопоставления ресурсов. http://www.webjars.org/documentation
<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>
весна-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 и скопировать его в ваш static swagger-ui.
Пожалуйста, проверьте простой пример рабочего плагина с аннотациями Spring MVC в этом репо:
https://github.com/khipis/swagger-maven-example
или для JAX-RS