Allbet Gaming

ug环球开户:Swagger之外的选择

admin 2020年07月18日 科技 50 1

今天给人人安利一款接口文档天生器——JApiDocs。

swagger想必人人都用过吧,异常利便,“功效也十分壮大”。「《若是》要说」swaager『有什么瑕』玷,想必就是注解写起来对照贫苦。《若是》我说有一款不用写注解,就可以天生文档《的》工具,“你心”动了吗?他就是我们今天《的》主角——JApiDocs。

<下面我>们一起来看看若何使用!

一、《添加依赖》

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.3</version>
</dependency>

二、设置天生参数

我们新建一个项目,然后随便写一个main「『方式』」,增添天生文档《的》设置,然后运行main「『方式』」。

DocsConfig config = new DocsConfig();
config.setProjectPath("F:\\Java{旅途}\\japi-docs"); // 项目根目录
config.setProjectName("japi-docs"); // 项目名称
config.setApiVersion("V1.0");       // 声明该API《的》版本
config.setDocsPath("F:\\test"); // 天生API 文档所在目录
config.setAutoGenerate(Boolean.TRUE);  // 《设置自动》天生
Docs.buildHtmlDocs(config); // 执行天生文档

三、编码规范

由于JApiDocs“是通”过剖析Java源码来实现《的》,因此《若是》要想实现想要《的》文档,照样需要遵照一定《的》规范。

3.1 『类注‘释’』、「『方式』」注‘释’和属性注‘释’

《若是》我们想天生类《的》注‘释’,“我们可以”直接在类上加注‘释’,也可以通过加@description来天生。

/**
 * “用户接口类”
 */
@RequestMapping("/api/user")
@RestController
public class UserController {}

/**
 * @author Java{旅途}
 * @Description “用户接口类”
 * @Date 2020-06-15 21:46
 */
@RequestMapping("/api/user")
@RestController
public class UserController {}

《若是》我们想天生「『方式』」《的》注‘释’,只能直接加注‘释’,不能通过加@description来天生。

/**
 * 查询用户
 * @param age 《岁数》
 * @return R<User>
*/
@GetMapping("/list")
public R<User> list(@RequestParam int age){

    User user = new User("Java{旅途}", 18);
    return R.ok(user);
}

JApiDocs可以自动天生实体类,关于实体类属性《的》注‘释’有三种「『方式』」,天生《的》效果都是一样《的》,如下:

/**
 * 【〖〖用户名〗称〗】
 */
private String name;
/**
 * 用户《岁数》
 */
private int age;
// 【〖〖用户名〗称〗】
private String name;
// 用户《岁数》
private int age;
private String name;// 【〖〖用户名〗称〗】
private int age;// 用户《岁数》

「他除了支持咱们」常用《的》model外,还支持IOS《的》model天生效果如下:

3.2 ‘请求参数’

《若是》提交《的》表单是 application/x-www-form-urlencoded 类型《的》key/value花样,则我们通过@param〖注解来获取参数〗,在参数后面添加注‘释’,示例如下:

/**
  * @param age 《岁数》
  */
@GetMapping("/list")
public R<User> list(@RequestParam int age){
    User user = new User("Java{旅途}", 18);
    return R.ok(user);
}

天生《的》文档效果如下:

‘请求参数’

参数名 类型 必须 形貌
age int 《岁数》

《若是》提交《的》表单是 application/json 类型《的》json数据花样,如下:

/**
  * @param user
  * @return
  */
@PostMapping("/add")
public R<User> add(@RequestBody User user){
    return R.ok(user);
}

天生《的》文档效果如下:

‘请求参数’

{
  "name": "string //【〖〖用户名〗称〗】",
  "age": "int //用户《岁数》"
}

3.3 响应效果

我们知道,《若是》Controller声明晰@RestController,SpringBoot会把返回《的》工具直接序列成Json数据花样返回给前端。 JApiDocs也利用了这一特征来剖析接口返回《的》效果,但由于JApiDocs是静态剖析源码《的》,因此你要明确指出返回工具《的》类型信息,JApiDocs支持继续、泛型、循环嵌套等庞大《的》类剖析。

因此我们不需要再写注‘释’,它会凭据我们《的》返回效{果举行剖析},效果如下:

返回效果:

{
  "code": "int",
  "msg": "string",
  "data": {
    "name": "string //【〖〖用户名〗称〗】",
    "age": "int //用户《岁数》"
  }
}

《最终》,我们天生《的》接口文档,如下:

四、高级设置

4.1 @ApiDoc

《若是》你不希望把所有《的》 接[口都导出,{我们可以在设置}中设置config.setAutoGenerate(Boolean.FALSE);然后再想要天生《的》接口上添加@ApiDoc。

@ApiDoc有以下三个属性:

  • result: 《这个可以直接声明返回》《的》工具类型,《若是》你声明晰,将会笼罩SpringBoot《的》返回工具
  • url: 请求URL,扩展字段,‘用于支持非’SpringBoot项目
  • method: 请求「『方式』」,扩展字段,‘用于支持非’SpringBoot项目
@ApiDoc(result = User.class, url = "/api/user/view", method = "post")

4.2 @Ignore

《若是》你不想导出工具内里《的》某个字段,可以给这个字段加上@Ignore注解,‘这样’JApiDocs导出文档《的》时刻就会自动忽略掉了。

public class User {
    @Ignore
    private int age;
}

五、总结

JApiDocs就先容到这里了,“优势劣势人人很容易”就看出来了。险些不需要注‘释’即可天生接口文档,仅有《的》几个注‘释’我们也可以通过ide来自动天生。然则JApiDocs〖不具备〗swagger在线调试功效。《若是》有一天JApiDocs支持在线调试后,那时刻一定会有一大波追随者,究竟写代码《的》谁喜欢写多余《的》注解!~

,

Allbet Gmaing《代理》

欢迎进入Allbet Gmaing《代理》(Allbet Game):www.aLLbetgame.us,欧博官网是欧博集团《的》《官方网》站。「欧博官网」开放Allbet注册、Allbe《代理》、Allbet电脑客户端、Allbet《手机版下载等业》务。

Allbet Gaming声明:该文看法仅代表作者自己,与阳光在线无关。转载请注明:ug环球开户:Swagger之外的选择
发布评论

分享到:

buy apple account:影人冀大片落场谷观众回流
1 条回复
  1. 欧博亚洲官方注册
    欧博亚洲官方注册
    (2020-07-18 00:02:58) 1#

    欧博亚洲客户端欢迎进入欧博亚洲客户端(Allbet Game):www.aLLbetgame.us,欧博官网是欧博集团的官方网站。欧博官网开放Allbet注册、Allbe代理、Allbet电脑客户端、Allbet手机版下载等业务。内容过于优秀

发表评论

◎欢迎参与讨论,请在这里发表您的看法、交流您的观点。