springboot+swagger2

1、swagger2背景介绍

为了减少每次开发接口都要编写一个word或者Md文档跟前端对接，并且一般更改需求了，都是只修改代码，经常会忘记更改接口文档。所以引入swagger2，节省时间，提高效率也便于维护。
其他就不多说了，想了解swagger的同学可以去它的官网https://swagger.io/，只不过使用相对麻烦，要学习它的编辑语法。然后还要使用swagger editor进行页面编辑，我就放弃了。

2、使用springboot+swagger2进行在线接口文档编辑

2.1、maven

目前最新的版本，使用的人也较多

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

2.2、创建swagger2的配置类

创建一个springboot项目，在启动类的子目录下创建配置类，启动类不需要添加额外注解，代码如下

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * “com.example.swagger.controller“是你控制器类的包名
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（填的数据对你的接口无影响，这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:端口号/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试使用Swagger2构建RESTful APIs")
                .description("作者:Author")
                .version("1.0")
                .build();

    }
}

此时启动项目，访问http://localhost:8080/swagger-ui.html#/即可出现页面。

但是仅仅这样对使用它的人来说不太友好，所以我们还需要在控制器上添加注解。

2.3、常用注解说明

@Api(tags = "")用在类上,多用于对类的描述。
@ApiOperation(value="", notes="")用在方法上,value是对方法的描述,notes可以进一步对方法进行解释说明。
@ApiImplicitParam(name="",value="",paramType="")用在方法上,对方法所需的参数进行声明,name是与形参名一致,value是对这个形参的描述,paramType是对参数传递方式的区分。
@ApiImplicitParams({})用在方法上,存放多个参数声明的注解,用逗号区分。
@ApiIgnore用在类或者方法上,可以让swagger2忽略这个类或者方法，也就是在Http页面不显示。

2.4、代码样例

实体类

//用户信息实体
public class User {
    private String neckname;
    
    private String companyName;
    
	get、set、toString()省略.....
	
}

//响应前端数据实体
public class JsonResult {

    private String result;

    private String cause;

    private Object data;

    public static JsonResult success(String cause, Object data) {
        return new JsonResult("success", cause, data);
    }
    public static JsonResult fail(String cause, Object data) {
        return new JsonResult("fail", cause, data);
    }
    
	get、set()省略........

控制器

@Api(tags = "展示swagger2注解的作用")
@RestController
@RequestMapping("swagger/api")
public class TestController {



    @GetMapping("sql/findById")
    @ApiOperation("测试get请求,根据用户id查找用户")
    @ApiImplicitParam(name = "userId",value = "用户id",required = true,paramType = "query")
    public JsonResult find(Integer userId){
        User user = null;
        if (userId==1){
            user = new User("任正非","华为");
        }
        if (userId==2){
            user = new User("李彦宏","百度");
        }
        return JsonResult.success("",user);
    }

    @PostMapping("sql/save")
    @ApiOperation(value = "测试post请求,保存用户信息")   
    public JsonResult sqlSave(@RequestBody User u) {
        JsonResult jsonResult = null;
        if (null != u) {
            jsonResult = JsonResult.success("保存成功", u);
        }
        return jsonResult;
    }

    @GetMapping("sql/session")
    @ApiOperation("测试请求头里的参数")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "team", value = "队名", paramType = "query"),
            @ApiImplicitParam(name = "sessionId", paramType = "header")
    })
    public String session(String team, HttpServletRequest request){
        String sessionId = request.getHeader("sessionId");
        if (sessionId !=null){
            return team+"总冠军!";
        }
        return "想得美";
    }
}

我访问我项目的地址http://localhost:8080/swagger-ui.html#
效果如下

现在即可点击任意方法,点Try it out进行尝试

2.5 提示

1、配置类里的两个注解必须加上。@Configuration、@EnableSwagger2，否则会导致访问页面失败。
2、控制器里的方法都需要设置明确的Http请求方法，否则会导致一个方法有八种请求。

2.6 结果

1、findById()方法我输入参数1;返回结果如下

{
  "result": "success",
  "cause": "",
  "data": {
    "neckname": "任正非",
    "companyName": "华为"
  }
}

2、sqlSave()方法我输入json对象:{"companyName": "阿里巴巴",  "neckname": "马云"}，返回如下

  "result": "success",
  "cause": "保存成功",
  "data": {
    "neckname": "马云",
    "companyName": "阿里巴巴"
  }
}

3、session（）方法我输入两个参数：sessionId=1234&team=湖人，返回如下

湖人总冠军！

3、总结

假设大家想让某个方法不在显示，可以在方法上加上@ApiIgnore的注解，即可忽略。如果你想加一些请求参数和成功返回结果的示例可以用@ApiOperation()中的note属性，使用字符串拼接一些请求参数和成功返回结果之类的方便前端进行调用测试。我把我的放出来给有需要的人看看

	//控制器类里的方法
	@GetMapping("/paymentOrder/searchCompany")
    @ApiOperation(value ="返回当前用户下的所有付款公司", notes = PaymentOrderNote.getCompanyListNote)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "keyWord",value = "搜索关键字",paramType = "query"),
            @ApiImplicitParam(name = "sessionid",paramType = "header")
    })
    public ResponseResult getCompanyList(String keyWord, HttpServletRequest request){
        ResponseResult responseResult = new ResponseResult();
        Lg.i(logger,"seleItemCondition-->{}", keyWord);
        String partnerId = LoginCacheFactory.getLoginCache(request, strRedis).getPartnerId();
        responseResult.sucess(paymentOrderService.getReceiveCompanyList(keyWord, partnerId));
        return responseResult;
    }
    
	//另一个类的静态方法
	public static final String getCompanyListNote= " Header参数: sessionid=登录时获取 "  +"\n"
                            +"请求参数:keyWord=非 "  +"\n"
                            +"成功返回参数: "  + "\n"
            +"{\n" +
            "  \"data\": [\n" +
            "    {\n" +
            "      \"company\": \"艾睿（非标）\",\n" +
            "      \"bankName\": \"BANK OF CHINA-FO TAN BRANCH\",\n" +
            "      \"bankAccount\": \"012-68892005245\",\n" +
            "      \"taxRate\": null,\n" +
            "      \"taxAmount\": null\n" +
            "    }\n" +
            "  ],\n" +
            "  \"result\": \"success\",\n" +
            "  \"cause\": null\n" +
            "}";

页面效果:

用了一段时间感觉还是比较方便的，但是也有缺点,就是必须服务开启swagger的接口文档才能访问,听说也有离线版的,生成一个html页面或者pdf文档的,但是目前还没来得及去做深入了解,等以后有用到了再发出来吧

参考：

https://blog.csdn.net/sanyaoxu_2/article/details/80555328