YDoc文档生成器图文使用教程

3,172 阅读3分钟

YDoc使用图文攻略

请使用1.0.8版本 已经开始发布到maven仓库,预计23号可以直接依赖,目前想要使用需要clone源码安装到本地

源码已经开源到github欢迎一起贡献源码,喜欢点个Star支持下

通用步骤

  1. 创建一个springboot的web工程 在这里插入图片描述
  2. 创建一个controller和一个pojo对象
//省略了get set 。。。
public class User {
   private Long id;
   private String name;
   private List<Order> us;
   private UserType type;
   public static class Order {
       private String     name;
       private BigDecimal price;
   }
}
// user Type是一个枚举类型
public enum UserType {
   ADMIN(0,"管理员"), SUPERMAN(1,"超人");
   UserType(int code,String description){
       this.code = code;
       this.description =description;

   };
   private int code;
   private String description;

}

控制器代码

@RestController
public class TestController {
   @GetMapping(value = "/get/{id}")
   public User test(@ParamDesc("id"),@PathVariable(value = "id") String id){
       User u = new User();
       return u;
   }
   @GetMapping(value = "/last")
   public User test(User user){
       return user;
   }
   @PostMapping(value = "/post")
   public User test1(@RequestBody User user){
       System.out.println(user);
       return user;
   }
   }
  
 

依赖maven库

      <dependency>
           <groupId>com.github.nobugboy</groupId>
           <artifactId>ydoc-spring-boot-starter</artifactId>
           <version>1.0.8</version>
       </dependency>

application.properties添加一条配置

    ydoc.enable=true

以上就是通用的基础环境,在平时的开发工程上只需额外依赖maven库和加一条配置即可

1. SwaggerUi方式

  1. 如果使用 SwaggerUi方式,需在启动类或配置类上加@EnableSwagger2
  2. 没了。就多了上面这一个操作
开始使用
  1. 启动工程,看到如下提示证明启动成功 在这里插入图片描述
  2. 访问http://localhost:8080/doc.html(如果修改了端口对应改一下)

在这里插入图片描述

  1. 此时接口文档已经生成,只是不太友好,我们来进行一下简单的改造(yapi的改造和该方式一致,下面就不重复该步骤)
@RestController(value = "用户相关接口")
public class TestController {
    @GetMapping(value = "/get/{id}",name = "根据id获取用户")
    public User test(@PathVariable(value = "id",name = "id") String id){
        User u = new User();
        return u;
    }
    @GetMapping(value = "/last",name = "get请求测试参数描述")
    public User test(User user){
        return user;
    }
    @PostMapping(value = "/post",name = "post请求测试参数描述")
    public User test1(@RequestBody User user){
        System.out.println(user);
        return user;
    }
}

public class User {
    @ParamDesc("用户主键id")
    private Long id;
    @ParamDesc("用户名称")
    private String name;
    @ParamDesc("订单集合")
    private List<Order> us;
    @ParamDesc("用户类型")
    private UserType type;

    public static class Order {
        @ParamDesc("订单名称")
        private String     name;
        @ParamDesc("价格")
        private BigDecimal price;
    }
}
//枚举类型重写了toString方法
public enum UserType {
    ADMIN(0,"管理员"), SUPERMAN(1,"超人");
    UserType(int code,String description){
        this.code = code;
        this.description =description;

    };
    private int code;
    private String description;
    @Override
    public String toString() {
        return Arrays.stream(values())
            .map(v -> v.code +"=" + v.description)
            .collect(Collectors.joining(","));
    }

}
  1. 重写启动程序,此时已经变成了非常友好的显示

在这里插入图片描述 发送一次请求试试 在这里插入图片描述

2. YApi方式

  1. 安装YAPI
  2. 配置项目token和YApi url即可

在YApi创建好项目,然后获取项目token,url就是访问YApi页面的路径即可 在这里插入图片描述

  1. 在配置文件加入两行配置
ydoc.enable=true
ydoc.host=http://localhost:3000
ydoc.token=265edcb30a90a9e3eaf2209c5ac04a7cfcf290ce36ef7218101f4ddfec321964
  1. 没了。就多了上面这一个操作
开始使用
  1. 启动工程,访问yapi页面,接口已经有了 在这里插入图片描述 此时所有文档已经生成完毕,点击mock地址可以发送随机mock参数。 在这里插入图片描述 发送一次请求试试(警告可以忽略,原因是枚举默认是数值类型) 在这里插入图片描述

如果发现YApi请求不到多半是路径不对,远程的YApi也支持访问本地的localhost的server,添加多个环境即可

在这里插入图片描述

Swagger原生模式(本质是为了兼容已经使用了Swagger配置的工程)

对于已经使用了swagger的工程来讲引入依赖,并开启native模式

ydoc.swagger-native=true

如果想要在程序启动时同步导入到YApi直接加入下面配置即可

ydoc.host=http://localhost:3000
ydoc.token=265edcb30a90a9e3eaf2209c5ac04a7cfcf290ce36ef7218101f4ddfec321964