Springfox (специфікація Swagger 2.0, поточна)
Springfox замінив Swagger-SpringMVC і тепер підтримує як специфікації Swagger 1.2, так і 2.0. Класи реалізації змінилися, що дозволило провести глибшу настройку, але з деякою роботою. Документація покращилася, але все ще потребує в деяких деталях додана для розширеної конфігурації. Стару відповідь щодо реалізації 1.2 все ще можна знайти нижче.
Залежність Мейвена
<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 використовує Джексона для прив'язки даних.
Додавати підтримку інтерфейсу Swagger зараз ще простіше. Якщо ви використовуєте 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, то, як зазначає 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 може трохи заплутати, але насправді неймовірно просто налаштувати. Найпростіша конфігурація вимагає створення 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.*");
}
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, який посилається на 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 для вашого проекту.