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.*");
}
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 для своего проекта.