Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API与接口方法,参数等保存同步,大大减少了接口开发人员的工作量.这个例子是我本地运行正常的,完整demo在文章最后。
第一步:在pom.xml引入相关jar
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.6.3</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>2.6.3</version> </dependency>
第二步:配置spring-servlet.xml
<!-- 激活@controller模式 --> <mvc:annotation-driven /> <!-- 配置包扫描位置(会在此包下扫描@controller控制器) --> <context:component-scan base-package="com.scan,com.bean" /> <!-- swagger静态文件路径 --> <mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/" cache-period="31556926"/> <mvc:default-servlet-handler /> <bean class="com.scan.config.SwaggerConfig" />
第三步:编写SwaggerConfig
package com.scan.config; import com.google.common.base.Predicate; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.EnableWebMvc; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.List; import static com.google.common.base.Predicates.or; import static com.google.common.collect.Lists.newArrayList; @Configuration @EnableSwagger2 @ComponentScan(basePackages = {"com.scan.controller"}) @EnableWebMvc public class SwaggerConfig extends WebMvcConfigurationSupport { @Bean public Docket customDocket() { // return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } private ApiInfo apiInfo() { Contact contact = new Contact("老王", "https://www.baidu.me", "baidu_666@icloud.com"); return new ApiInfo("Blog前台API接口",//大标题 title "Swagger测试demo",//小标题 "0.0.1",//版本 "www.baidu.com",//termsOfServiceUrl contact,//作者 "Blog",//链接显示文字 "https://www.baidu.me"//网站链接 ); } }
第四步:控制层的配置
@Controller @RequestMapping("/userController") @Api(tags = "二:用户信息") //swagger分类标题注解 public class UserController { @RequestMapping(value = "/listCompound", method = RequestMethod.GET) @ResponseBody
//swagger返回值注解 @ApiResponses(value = { @ApiResponse(code = 500, message = "系统错误"), @ApiResponse(code = 200, message = "0 成功,其它为错误,返回格式:{code:0,data[{}]},data中的属性参照下方Model", response = UserVo.class) }) @ApiOperation(httpMethod = "GET", value = "个人信息")//swagger 当前接口注解 public String listCompound( @ApiParam(required = true, name = "start", value = "start") int start, int limit, @ApiParam(required = false, name = "userName", value = "名称模糊查询") String userName) { List<UserVo> data = new ArrayList<UserVo>(); String msg = data.size() > 0 ? "" : "没有查询到相关记录"; Result result = new Result(); result.setMsg(msg); result.setCode(0); result.setData(data); return JSONObject.toJSONString(result); }
第五步:下载swaggerUi,将下载后的文件解压,将dist目录下的文件,复制到webapp下的swagger目录中(这个目录的名字自定义,但要和spring-servert.xml中(<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/") 的名称要一致,修改index.html中文档加载的地址.
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
//url: "http://petstore.swagger.io/v2/swagger.json",
url:"http://127.0.0.1:8080/swagger-spring/v2/api-docs.do",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
如果以上配置正确,在浏览器中输入http://127.0.0.1:8080/swagger-spring/swagger/index.html,将会出现如下界面:
swagger注解说明
1、与模型相关的注解,用在bean上面
@ApiModel:用在bean上,对模型类做注释;
@ApiModelProperty:用在属性上,对属性做注释
2、与接口相关的注解
@Api:用在controller上,对controller进行注释;
@ApiOperation:用在API方法上,对该API做注释,说明API的作用;
@ApiImplicitParams:用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明;
@ApiImplicitParam:用在@ApiImplicitParams注解中,也可以单独使用,说明一个请求参数的各个方面,该注解包含的常用选项有:
paramType:参数所放置的地方,包含query、header、path、body以及form,最常用的是前四个。
name:参数名;
dataType:参数类型,可以是基础数据类型,也可以是一个class;
required:参数是否必须传;
value:参数的注释,说明参数的意义;
defaultValue:参数的默认值;
@ApiResponses:通常用来包含接口的一组响应注解,可以简单的理解为响应注解的集合声明;
@ApiResponse:用在@ApiResponses中,一般用于表达一个响应信息
code:即httpCode,例如400
message:信息,例如"操作成功"
response = UserVo.class 这里UserVo是一个配置了@ApiModel注解的对像,该是对像属性已配置 @ApiModelProperty,swagger可以通过这些配置,生 成接口返回值
- 为了在swagger-ui上看到输出,至少需要两个注解:@Api和@ApiOperation
- 即使只有一个@ApiResponse,也需要使用@ApiResponses包住
- 对于@ApiImplicitParam的paramType:query、form域中的值需要使用@RequestParam获取, header域中的值需要使用@RequestHeader来获取,path域中的值需要使用@PathVariable来获取,body域中的值使用@RequestBody来获取,否则可能出错;而且如果paramType是body,name就不能是body,否则有问题,与官方文档中的“If paramType is "body", the name should be "body"不符。