pom.xml
<!-- Swagger -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-core</artifactId> <!--swagger核心代码-->
<version>1.5.8</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId> <!--swagger和该框架的集成-->
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId> <!--swagger-ui和和swagger-ui的集成>
<version>2.4.0</version>
</dependency>
当JAR包添加成功后,在项目中会出现如下系列JAR包:
SwaggerConfiguration.java
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
SwaggerWebMvcConfigurerAdapter.java
@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.xx.travel.csc.stat.controller")
public class SwaggerWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter {
@Bean
public ViewResolver viewResolver() {
InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();
viewResolver.setViewClass(JstlView.class);
viewResolver.setPrefix("/WEB-INF/views/");
viewResolver.setSuffix(".jsp");
return viewResolver;
}
@Bean
public MessageSource messageSource() {
ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
messageSource.setBasename("messages");
return messageSource;
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
super.addResourceHandlers(registry);
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
}
Controller实例中的应用
只要在我们的Controller里面增加注解 ApiOperation和ApiParam 即可。然后再swagger-ui界面就能看到我们相关api的描述!
@Controller
@RequestMapping(value = "/stat")
public class SwaggerController {
@ResponseBody
@RequestMapping(value = "/helloworld", method = RequestMethod.GET)
@ApiOperation(nickname = "swagger-helloworld", value = "Swagger的世界", notes = "测试HelloWorld")
public String helloWorld(@ApiParam(value = "昵称") @RequestParam String nickname) {
return "Hello world, " + nickname;
}
@ResponseBody
@RequestMapping(value = "/objectio", method = RequestMethod.POST)
@ApiOperation(nickname = "swagger-objectio", value = "Swagger的ObjectIO", notes = "测试对象输入输出")
public SwaggerOutput objectIo(@ApiParam(value = "输入") @RequestBody SwaggerInput input) {
SwaggerOutput output = new SwaggerOutput();
output.setId(input.getId());
output.setName("Swagger");
return output;
}
}
与上面注解对应的ui界面显示
Web界面
启动项目,输入Http://{Path}/swagger-ui.html,就可以给前端展示相关的API文档,并像使用Postman以及Curl命令一样,通过Web界面进行接口测试。
在有些项目中spring mvc的请求是以某一后缀(url-pattern, 例如 .do)结尾的, 这样就要做一些必要的修改,在swagger-ui.js中,修改如下
opts.responseContentType = $('div select[name=responseContentType]', $(this.el)).val();
opts.requestContentType = $('div select[name=parameterContentType]', $(this.el)).val();
$('.response_throbber', $(this.el)).show();
// here, add suffix
var suffix = ".do";
if (!this.model.path.endsWith(suffix)) {
this.model.path = this.model.path + suffix;
}
if (isFileUpload) {
$('.request_url', $(this.el)).html('<pre></pre>');
$('.request_url pre', $(this.el)).text(this.invocationUrl);
opts.useJQuery = true;
map.parameterContentType = 'multipart/form-data';
this.map = map;
return this.model.execute(map, opts, this.showCompleteStatus, this.showErrorStatus, this);
} else {
this.map = map;
return this.model.execute(map, opts, this.showCompleteStatus, this.showErrorStatus, this);
}
别人的一个集成实例地址:
https://github.com/pumadong/cl-roadshow/tree/master/roadshow-swagger