准备工作

　　首选需要一个springmvc项目，这里我用的是springboot+maven来快速构建，要使用swagger只需要在maven中添加依赖包就行：

 1 <dependency>
 2     <groupId>io.springfox</groupId>
 3     <artifactId>springfox-swagger2</artifactId>
 4     <version>2.6.1</version>
 5 </dependency>
 6 <dependency>
 7     <groupId>io.springfox</groupId>
 8     <artifactId>springfox-swagger-ui</artifactId>
 9     <version>2.6.1</version>
10 </dependency>

　　然后创建一个UserController，然后再定义个Login的Action，定义请求和响应实体，由于api接口需要对请求和响应属性列做文字描述，并且上面我们在项目中加了swagger包，因此以直接在实体和Action使用特性来增加具体文字描述：

 1 @RestController
 2 @Api(tags = "会员接口")
 3 public class UserController {
 4 
 5     @PostMapping("/login")
 6     @ApiOperation(value = "登录")
 7     public LoginRp login(@RequestBody LoginRq rq) {
 8         LoginRp rp = new LoginRp();
 9 
10         if (rq.getUserName().isEmpty() || rq.getUserPwd().isEmpty()) {
11             rp.setCode(EmApiCode.登录账号或密码不能为空.getVal());
12             return rp;
13         }
14 
15         if (rq.getUserName().equals("shenniu001") && rq.getUserPwd().equals("123")) {
16             rp.setCode(EmApiCode.成功.getVal());
17 
18             rp.setToken(UUID.randomUUID().toString());
19         } else {
20             rp.setCode(EmApiCode.失败.getVal());
21         }
22         return rp;
23     }
24 
25 }

　　请求和响应实体类：

 
   View Code

　　注解简单说明：

　　@Api：同一类接口的总描述，一般用于Controller标记

　　@ApiOperation(value = "登录")：在Action上标记，描述这个Action接口具体干什么

　　@ApiModel：请求响应实体类class上的标记

　　@ApiModelProperty(value = "登录账号")：请求响应属性上的标记，用来描述该属性具体说明

快速构建api文档

　　准备做完后要生成文档，还需要自定义两个封装类，如下Swagger2类：

 1 @Configuration
 2 @EnableSwagger2
 3 public class Swagger2 {
 4 
 5     @Bean
 6     public Docket createRestApi() {
 7 
 8         return new Docket(DocumentationType.SWAGGER_2)
 9                 .select()
10                 //过滤默认错误api
11                 .paths(Predicates.not(PathSelectors.regex("/error.*")))
12                 .build()
13                 .apiInfo(apiInfo());
14     }
15 
16     //常用的细节
17     //过滤指定的action
18     //添加授权token列
19     //添加上传文件列
20     private ApiInfo apiInfo() {
21         return new ApiInfoBuilder()
22                 .title("开车接口文档")
23                 .description("该文档只允许我使用")
24                 //版本
25                 .version("0.0.0.1")
26                 .contact("作者：[email protected]")
27                 .build();
28     }
29 }

　　这个类主要初始化一些全局文档的说明和版本并且构架api文档；上面是生成文档，但是具体文档数据源用从swagger的SwaggerResourcesProvider中来，因此自定义的DocumentationConfig类实现SwaggerResourcesProvider接口，如下：

 1 @Component
 2 @Primary
 3 public class DocumentationConfig implements SwaggerResourcesProvider {
 4     @Override
 5     public List<SwaggerResource> get() {
 6         List resources = new ArrayList<>();
 7         resources.add(swaggerResource("开车接口api", "/v2/api-docs", "0.0.0.1"));
 8         resources.add(swaggerResource("坐车接口api", "/v2/api-docs", "0.0.0.1"));
 9         return resources;
10     }
11 
12     private SwaggerResource swaggerResource(String name, String location, String version) {
13         SwaggerResource swaggerResource = new SwaggerResource();
14         swaggerResource.setName(name);
15         swaggerResource.setLocation(location);
16         swaggerResource.setSwaggerVersion(version);
17         return swaggerResource;
18     }
19 }

　　主要加载文档的数据源，数据源主要通过 resources.add(swaggerResource("坐车接口api", "/v2/api-docs", "0.0.0.1")) 添加，倘若你想添加其他api接口源就可以在这里进行配置，直接把/v2/api-docs改成你的url就行，这个地方也是springcloud微服务api添加的入口；当编码完成后我们来看看效果：

　　能成功加载出我们的login接口，而且有一些说明性的文字；再来看看我们请求和响应的参数是否有说明：

　　请求和响应都有了相应的说明，是不是挺简单；

常用的细节

　　1.过滤默认错误api

　　由于springmvc封装有错误的controller，因此swagger也会把这个展示出来，因为是扫描的所有controller来展示swagger文档的，故此我们需要屏蔽这些对于对接方没用的接口；这里通过设置paths的不匹配就行了，以下代码：

1 //过滤默认错误api
2 paths(Predicates.not(PathSelectors.regex("/error.*")))

　　2.添加授权token列

　　对于接口验证来说通常需要个token并且放在header里面，这里我们直接在swagger上增加一个显示的token，只需要在build之前增加一个header参数：

 1 @Bean
 2     public Docket createRestApi() {
 3 
 4         List<Parameter> pars = new ArrayList<>();
 5         //添加授权token
 6         ParameterBuilder tokenPar = new ParameterBuilder();
 7         tokenPar.name("token").description("授权token 注：登录不需要填，只有post方式的接口必填").
 8                 modelRef(new ModelRef("string")).
 9                 parameterType("header").required(false).build();
10         pars.add(tokenPar.build());
11 
12         return new Docket(DocumentationType.SWAGGER_2)
13                 .select()
14                 .paths(Predicates.not(PathSelectors.regex("/error.*")))
15                 .build()
16                 .globalOperationParameters(pars)
17                 .apiInfo(apiInfo());
18    }

　　这个时候每个action接口文档块中都会增加一个token列，type是header类型：

　　3.添加上传文件列

　　通常api接口都包含一个公共上传接口，为了让swagger文档更方便，我们需要让她支持下上传；首先这样定义一个上传接口：

1 @PostMapping(value = "/upload",headers = "content-type=multipart/form-data")
2     @ApiOperation(value = "上传")
3     public BaseRp upload(@ApiParam(value = "上传的文件",required = true) @RequestBody MultipartFile file) {
4         BaseRp rp = new BaseRp();
5 
6         rp.setMessage("上传文件名："+file.getOriginalFilename());
7 
8         return rp;
9     }

　　其他就不用再设置了，仅仅如此运行后效果：

　　咋们点击“选择文件”测试下上传，点击try能够得到如下成功运行的效果图：

http://news.cgn5379.cn/
http://www.kog1435.cn/
http://www.rik3314.cn/
http://news.zmj4226.cn/
http://news.igf1400.cn/
http://www.bcu6005.cn/
http://news.esz4596.cn/
http://news.dli5822.cn/
http://www.vsb9575.cn/
http://news.dto7731.cn/
http://news.eqn5017.cn/
http://news.lkg4662.cn/
http://www.xrr9518.cn/
http://www.qfk7654.cn/
http://www.txr3194.cn/
http://news.nkc4539.cn/
http://www.xjy3902.cn/
http://www.ciw9360.cn/
http://news.pzx0011.cn/
http://www.eqv5313.cn/
http://www.qdn5355.cn/
http://www.qri2046.cn/
http://www.wxm6819.cn/
http://news.bpj4889.cn/
http://www.blm3653.cn/
http://news.ixa0880.cn/
http://news.tvz4241.cn/
http://www.nkc4539.cn/
http://www.ehe5445.top/
http://www.axs9870.cn/
http://news.hiv8337.cn/
http://news.wvh4263.cn/
http://news.myy9223.cn/
http://www.hud3144.cn/
http://www.kdz0246.cn/
http://news.pck8038.cn/
http://news.mtr5072.cn/
http://news.mzj8672.cn/
http://www.ixa0880.cn/
http://www.gdk7028.cn/
http://news.blm3653.cn/
http://www.yif9712.cn/
http://news.sfx6922.cn/
http://news.ric5056.cn/
http://www.vii0197.cn/
http://www.ybc8953.cn/
http://news.nwf3326.cn/
http://news.nlc4773.cn/
http://news.uqt9445.cn/
http://news.zbb7727.cn/
http://news.ajj5951.cn/
http://news.arf0717.cn/
http://news.cqu4082.cn/
http://news.dsx1888.cn/
http://news.ass0795.cn/
http://news.cyj2776.cn/
http://www.wqr1047.cn/
http://news.mox2684.cn/

springmvc+swagger构建Restful风格文档