swagger的API自动生成文档、自动生成其他语言请求文档、所有请求导入postman

一、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")
@Slf4j
public 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文档，请求地址：http://10.10.200.165:10901/swagger-ui.html

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

以上述http://10.10.200.165:10901/swagger-ui.html为例

生成请求Json的地址：http://10.10.200.165:10901/v2/api-docs

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

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

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

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

 swagger json url,上面的http://10.10.200.165:10901/v2/api-docs便可以

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.最后的具体文件如下图，可以修改一下，实现快速开发