本文共 3877 字，大约阅读时间需要 12 分钟。

一、swagger的API自动生成文档

    1.maven引入swagger的相关jar

   
    2.6.1
   

       
    
     io.springfox
        
    
     springfox-swagger2
        
    
     ${swagger.version}
    
   
       
    
     io.springfox
        
    
     springfox-swagger-ui
        
    
     ${swagger.version}
    
   

    2.配置SwaggerConfig 配置类

    @Profile指定了只在dev test 环境有效，正式环境是访问不到的

    也可以指定Header参数

@EnableSwagger2@Configuration@Profile({
 "dev", "test"})public class SwaggerConfig {    @Bean    public Docket createRestApi() {        //添加head参数start        ParameterBuilder tokenPar = new ParameterBuilder();        List
   
     pars = new ArrayList
    
     ();        tokenPar.name("client").description("渠道").defaultValue("SENIOR_TEACH").modelRef(new ModelRef("string"))                .parameterType("header").required(true).build();        pars.add(tokenPar.build());        //添加head参数end        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.lexue.edu"))                .paths(PathSelectors.any())                .build()                .globalOperationParameters(pars);    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("Lexue User Module APIs")                .description("Lexue User Module APIs")                .version("1.0")                .build();    }}
    
   

3.Controller类中增加文档标签

@Api @ApiOperation @ApiParam @ApiIgnore等

@Api(tags={
 "account"})@RestController("accountController")@Slf4jpublic class AccountController {    @ApiOperation(value = "查询用户余额",notes = "查询用户余额信息")    @GetMapping(value="/account/{version}/balance")    @UserLoggedCheck    public AppResponse
   
     balance(@PathVariable("version") String version            ,@ApiIgnore UserLoggedInfo userLoggedInfo){        AppResponse response;        response.setTsrp(System.currentTimeMillis());        return response;    }    @GetMapping(value="/account/{version}/trans")    @UserLoggedCheck    @ApiOperation(value = "查询账户交易记录", notes = "查询账户交易记录，分页查询")    public AppResponse
    
     
      > trans(@PathVariable("version") String version            ,@ApiParam(value = "当前页码",defaultValue = "1") @RequestParam(name = "cur",required = false,defaultValue = "1") int cur            ,@ApiParam(value = "页面大小",defaultValue = "20") @RequestParam(name = "size",required = false,defaultValue = "20") int size            ,@ApiIgnore UserLoggedInfo userLoggedInfo){        AppResponse response;        response.setTsrp(System.currentTimeMillis());        return response;    }}
     
    
   

4.返回对象中增加swagger的标签

@ApiModelProperty

@Data@JsonInclude(value = JsonInclude.Include.NON_NULL)public class AccountTransResponse {   @ApiModelProperty(value = "交易类型",example = "1")   @JsonProperty("trtp")   private TransactionRecordType transType ;   @ApiModelProperty(value = "交易流水",example = "ls1323454561313")   @JsonProperty("trsl")   private String transSerial;   @ApiModelProperty(value = "交易金额,单位分",example = "10000")   @JsonProperty("trac")   private long transAccount  ;   @ApiModelProperty(value = "交易时间戳，毫秒",example = "1515746099000")   @JsonProperty("trts")   private long transTimestamp;}

5.查询swagger文档，请求地址：

 二：swagger将生成的文档请求，导入postman列表中，便于本地调试

以上述为例

生成请求Json的地址：

之后postman的import from link引入json请求地址，具体看下图

导入后的具体效果图如下：

三：swagger生成其他语言请求的文档

1.前提安装java 引入swagger-codegen-cli-2.3.0.jar(放置到本地) 

 swagger json url,上面的便可以

2.java -jar swagger-codegen-cli-2.3.0.jar 可以查看swagger能生成文档支持的语言

3.java -jar swagger-codegen-cli-2.3.0.jar generate -i http://10.10.200.165:10904/v2/api-docs?group=learn -l typescript-angular -o typejs

上述就是执行生成angular语言文档的命令行，在当前文件夹下创建typejs 存储生成的文档

【参数说明】

  -jar 指定 swagger-codegen-cli-2.2.1.jar 的位置，绝对路径、相对路径均可；

  -i 指定 swagger.json 的位置，本地路径、网络路径均可；

  -l 指定客户端代码的语言；

  -o 指定代码生成的位置；

  --model-package 指定model代码的包名；

  --api-package 指定api代码的包名；

生成的文件目录情况

4.最后的具体文件如下图，可以修改一下，实现快速开发