Ответ 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 для вашего проекта.