【Spring Security OAuth2】- 【使用Spring MVC开发RESTful API】 使用swagger自动生成html文档

作者简介：大家好，我是smart哥，前中兴通讯、美团架构师，现某互联网公司CTO

联系qq：184480602，加我进群，大家一起学习，一起进步，一起对抗互联网寒冬

学习必须往深处挖，挖的越深，基础越扎实！

阶段1、深入多线程

阶段2、深入多线程设计模式

阶段3、深入juc源码解析

阶段4、深入jdk其余源码解析

阶段5、深入jvm源码解析

码哥源码部分

码哥讲源码-原理源码篇【2024年最新大厂关于线程池使用的场景题】

码哥讲源码【炸雷啦！炸雷啦！黄光头他终于跑路啦！】

码哥讲源码-【jvm课程前置知识及c/c++调试环境搭建】

​​​​​​码哥讲源码-原理源码篇【揭秘join方法的唤醒本质上决定于jvm的底层析构函数】

码哥源码-原理源码篇【Doug Lea为什么要将成员变量赋值给局部变量后再操作？】

码哥讲源码【你水不是你的错,但是你胡说八道就是你不对了！】

码哥讲源码【谁再说Spring不支持多线程事务，你给我抽他！】

终结B站没人能讲清楚红黑树的历史，不服等你来踢馆！

打脸系列【020-3小时讲解MESI协议和volatile之间的关系，那些将x86下的验证结果当作最终结果的水货们请闭嘴】

使用swagger自动生成html文档

本节内容

• 使用swagger自动生成html文档
• 使用WireMock快速伪造restful服务

前后分离并行开发的时候（当然不是一个人从前到后都干那种）；那么提供文档就很有必要了。

光看文档不是那么的直观。伪造服务可能更直观（个人感觉而言，文档详细，自己在postman这种工具中去调用也是一样的）

初体验

添加两个依赖

    // 扫描程序生成文档数据
    // http://springfox.github.io/springfox/docs/current/
    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
    // 提供可视化界面
    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

添加注解开启swagger

    @EnableSwagger2
    public class DemoApplication {

启动程序后，访问：http://localhost:8080/swagger-ui.html 就能看到一个界面。里面会显示该程序中所有的的controller断点。并扫描该断点的注解等信息进行分析一些有关断点的信息；

可以点击Try it out按钮发起请求，然后在界面上会把响应结果返回；

这样看的确挺方便的；

使用注解自定义信息

定义api描述

    @ApiOperation(value = "用户查询服务")  // 方法描述
    public List<User> query(UserQueryCondition condition) {

定义请求字段信息，如果参数是一个对象，则需要在对象字段上添加注解

    public class UserQueryCondition {
        @ApiModelProperty(value = "用户名")
        private String username;
复制代码

不是对象的字段描述

    @JsonView(User.UserDetailView.class)
    public User getInfo(@ApiParam(value = "用户id") @PathVariable String id) {

上面是3个常用的注解，其他的官网文档查看；

个人感觉：相对于spring-restdocs-asciidoctor代码入侵太严重，我个人是不太愿意用的；但是的确很方便能看到所有提供的服务；包括spring框架提供的

下一节：使用WireMock快速伪造restful服务