Spring Boot1.5 使用 Swagger文档接口

Swagger 简介

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分：

1. Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
2. Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
3. Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

为什么要使用 Swagger

1. 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
2. 跨语言性，支持 40 多种语言。
3. Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
4. 还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试

  正是有这些优点， 维护文档不那么麻烦了， 才试一下这个功能如何

遇到坑的地方, 这两个传参数不一样，后台 httpClient第三方插件提交请求，默认是map格式提交，无法得到JSON，

（1） public JSONObject device_char(@RequestParam Map maparams) {}

（2）public JSONObject flow_charsummary(@RequestBody JSONObject jsonparams) {

第一条 httpClient 请求必须用@RequestParam，

第二条，比如是postman或者 AJAX提交 都可以接收到参数，提交类型 application/json;charset=UTF-8

报错如下

httpclient Content type 'application\/x-www-form-urlencoded;charset=UTF-8' not supported

第一， 依赖包

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.6.RELEASE</version>
    </parent>

     <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

 

第二  写一个配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(
                RequestHandlerSelectors.basePackage("com.zenlayer.ad.controller")).paths(PathSelectors.any()).build();

       /* useDefaultResponseMessages(false).globalResponseMessage(RequestMethod.GET, newArrayList(new ResponseMessageBuilder().code(500)
                .message("服务器发生异常").responseModel(new ModelRef("Error")).build(), new ResponseMessageBuilder().code(403).message("资源不可用")
                .build());*/
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("使用Swagger2构建RESTful API").description("rest api 文档构建").version("1.0").build();
    }

}

 

 

第三， 启动之后， 就应该可能看到一个界面了 根据自己项目名称和端口号，http://localhost:9091/flow_group_gpapi/swagger-ui.html#/，这是我本机项目，目录基本swagger-ui.html#/ 基本不变的，集成他的界面， 里面还可以进行测试接口

 

第四，就是代码示例  注释掉的代码参数也是可以的，主重要的是 paramType = "query" 参数要加入， 否则从前台传不了参数

   @GetMapping("/gpapi/webflow/flow/test")
    @ApiResponses({@ApiResponse(code = 400, message = "服务器内部异常"), @ApiResponse(code = 500, message = "权限不足")})
    @ApiOperation(value = "swagger接口API测试")//httpMethod = "post",
    @ApiImplicitParams({@ApiImplicitParam(name = "snmp_id", value = "snmp_id", paramType = "query", required = true),
            @ApiImplicitParam(name = "port_index", value = "port_index", paramType = "query", required = true),
            @ApiImplicitParam(name = "timezone", value = "UTC PST Asia/Shanghai", paramType = "query")})
    //public JSONObject swaggerTest(String snmp_id, String port_index, String timezone) {
    public JSONObject swaggerTest(@RequestParam("snmp_id") String snmp_id, @RequestParam("port_index") String port_index,
                                  @RequestParam("timezone") String timezone) {
        JSONObject json = new JSONObject();
        json.put("snmp", snmp_id);
        json.put("port_index", port_index);
        json.put("timezone", timezone);
        return json;
    }

第五 还是代码传参数问题，这次是post请求， 但是界面参数我想封装成 JSONObject ，界面就不好测试了，最好的结果是，@ApiImplicitParam注入的参数， 能直接拿出来用就OK， 一直没有找到解决方法

 @PostMapping("/gpapi/webflow/flow/snmp_index_char")
    @ApiOperation(value = "单个端口流量查询")//httpMethod = "post",
    @ApiImplicitParams({@ApiImplicitParam(name = "snmp_id", value = "snmp_id", paramType = "query", required = true),
            @ApiImplicitParam(name = "port_index", value = "port_index", paramType = "query", required = true),
            @ApiImplicitParam(name = "start", value = "开始时间", paramType = "query", required = true),
            @ApiImplicitParam(name = "end", value = "结束时间 2018-01-01 00:00:00", paramType = "query", required = true),
            @ApiImplicitParam(name = "flag", value = "1  portal 2 portal2.0 3 oss 4导出数据", paramType = "query", required = true),
            @ApiImplicitParam(name = "is_data", value = "1 不返回详细数据，只有95之类的值", paramType = "query", required = true),
            @ApiImplicitParam(name = "timezone", value = "UTC PST Asia/Shanghai", paramType = "query")})
    public JSONObject snmp_index_char(@RequestBody JSONObject jsonparams) {

这样前台传的JSON过来， 是可以得到数据，但是API界面 如下，必填参数，相当纠结

第六种方式 ， 就是利用bean 封装好的属性了， 这样是可以达到想要的目的

 

定义model类

@ApiModel( description = "学生")
public class Student {
    @ApiModelProperty(value = "主键id")
    private String id;
    @ApiModelProperty(value = "名称", required = true)
    private String name;
    @ApiModelProperty(value = "年龄", required = true)
    private int age;
…
}

在方法使用

@RequestMapping(value = "/update", method = {RequestMethod.POST})
@ApiOperation(value = "添加学生记录", notes="传递复杂对象DTO",produces = "application/json")
public int update(@RequestBody Student student){
    System.out.println("update student = " + student);
    return 1;
}

结果显示如下

 

 

使用模型 作为参数应该是最规范的， 这样参数说明都有，更好维护，用这个当成一般开发文档，还是可以的。下面贴些抄来的参数说明。

相关注解说明

在本章节中我将给出一些 Swagger 中常用的注解以及其常用的属性，并对其一一解释，方便您查看。

Controller 相关注解

@Api: 可设置对控制器的描述。

表 1. @Api 主要属性

注解属性	类型	描述
tags	String[]	控制器标签。
description	String	控制器描述（该字段被申明为过期）。

接口相关注解

1. @ApiOperation: 可设置对接口的描述。

   表 2. @ApiOperation 主要属性

   注解属性	类型	描述
   value	String	接口说明。
   notes	String	接口发布说明。
   tags	Stirng[]	标签。
   response	Class<?>	接口返回类型。
   httpMethod	String	接口请求方式。

2. @ApiIgnore: Swagger 文档不会显示拥有该注解的接口。
3. @ApiImplicitParams: 用于描述接口的非对象参数集。
4. @ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。

   表 3. @ApiImplicitParam 主要属性

   注解属性	描述
   paramType	查询参数类型，实际上就是参数放在那里。取值： path：以地址的形式提交数据，根据 id 查询用户的接口就是这种形式传参。 query：Query string 的方式传参。 header：以流的形式提交。 form：以 Form 表单的形式提交。
   dataType	参数的数据类型。取值： Long String
   name	参数名字。
   value	参数意义的描述。
   required	是否必填。取值： true：必填参数。 false：非必填参数。

Model 相关注解

1. @ApiModel: 可设置接口相关实体的描述。
2. @ApiModelProperty: 可设置实体属性的相关描述。

   表 4. @ApiModelProperty 主要属性

   注解属性	类型	描述
   value	String	字段说明。
   name	String	重写字段名称。
   dataType	Stirng	重写字段类型。
   required	boolean	是否必填。
   example	Stirng	举例说明。
   hidden	boolean	是否在文档中隐藏该字段。
   allowEmptyValue	boolean	是否允许为空。
   allowableValues	String	该字段允许的值，当我们 API 的某个参数为枚举类型时，使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。