2021-01-22

SWAGGER2调研以及使用

在调研的过程中发现：在前后端分离的开发模式中，api文档的使用极大的方便了程序员们。
Swagger 是一个规范和完整的框架，用于生成、描述、调用可视化 RESTful 风格的 Web 服务。

1. 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3. 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4. 可测性 (直接在接口文档上进行测试，以方便理解业务)

---

配置：

1、引入依赖

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

        <!-- 接口API生成html文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

2、创建启动类

/**
 * @Description: springboot利用swagger构建api文档
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //four.yiqi.controller"， web层所在的目录
                .apis(RequestHandlerSelectors.basePackage("four.yiqi.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档---数据源管理系统")
                .description("简单优雅的restfun风格")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

启动主类后，登录http://localhost:8080/swagger-ui.html#/,查看效果：

3、swagger基础注解的介绍
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象实体来作为入参
@ApiProperty：用对象接实体收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams： 多个请求参数

4、简单应用、
编写controller进行测试

@RestController
@RequestMapping("/api")
public class HistoryCtrl {
    @Resource
    private HistorySrvImpl historySrv;
    @ApiOperation(value = "根据userid进行历史操作查询", notes = "根据id进行历史操作查询")
    @ApiImplicitParam(name = "userid", value = "用户id", required = true, dataType = "String", paramType = "path")
    @GetMapping("/select/{userid}")
    public JsonResult selHistory(@PathVariable String userid) {
        JsonResult res = new JsonResult(1, "查询成功");

        List<History> list = historySrv.selHistory(userid);
        if (list.size() == 0) {
            res.setData(list);
        } else {
            List datas = new ArrayList(list.size());
            for (History history : list) {
                try {
                    Map map = BeanUtils.describe(history);
                    SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
                    String createTime = sdf.format(history.getTime());
                    map.put("time", createTime);
                    map.remove("class");
                    datas.add(map);
                } catch (IllegalAccessException e) {
                    e.printStackTrace();
                } catch (InvocationTargetException e) {
                    e.printStackTrace();
                } catch (NoSuchMethodException e) {
                    e.printStackTrace();
                }
            }
            res.setData(datas);
        }

        return res;
    }
}

@RestController
@RequestMapping("/api")
public class UserCtrl {
    @Resource
    private UserSrvImpl userSrv;
    @Resource
    private HistorySrvImpl historySrv;

    @ApiOperation(value = "根据userid,money进行存款", notes = "根据userid,money进行存款")
    @ApiImplicitParam(name = "userid", value = "用户id", required = true, dataType = "String", paramType = "path")
    @PostMapping("/add")
    public JsonResult addMoney(@RequestBody User user) {
        JsonResult res=new JsonResult(0,"成功");
        userSrv.addMoney(user);
        History history = new History(user.getUserid(), "存款", user.getMoney(), new Date());
        historySrv.insertHistory(history);
        return res;
    }

    @ApiOperation(value = "根据userid,money进行取款", notes = "根据userid,money进行取款")
    @ApiImplicitParam(name = "userid", value = "用户id", required = true, dataType = "String", paramType = "path")
    @PostMapping("/subtract")
    public JsonResult subtractMoney(@RequestBody User user) {
        JsonResult res=new JsonResult(0,"取款成功");

      User user1=  selMoneyByUserid(user.getUserid());
        if (user.getMoney()>user1.getMoney()){
            res.setCode(1);
            res.setMsg("账户余额不足");
        }else{

            userSrv.subtractMoney(user);
            History history = new History(user.getUserid(), "取款", user.getMoney(), new Date());
            historySrv.insertHistory(history);
        }
        return res;
    }
    @ApiOperation(value = "根据userid进行账户余额查询", notes = "根据userid查询余额")
    @ApiImplicitParam(name = "userid", value = "用户id", required = true, dataType = "String", paramType = "path")
    @PostMapping("/selMoneyByUserid/{userid}")
    public User selMoneyByUserid(@PathVariable String userid) {

        User user = userSrv.selMoneyByUserid(userid);
        return  user;

    }

}

打开浏览器出现如下效果：

进行测试 传入userid=1:

至此调研结束

感谢：
https://blog.youkuaiyun.com/zyjtoto/article/details/96480749?utm_medium=distribute.pc_relevant.none-task-blog-baidujs_baidulandingword-3&spm=1001.2101.3001.4242