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