Api2Doc生成 Restful API 文档
1,引入maven
<dependency>
<groupId>com.github.terran4j</groupId>
<artifactId>terran4j-commons-api2doc</artifactId>
<version>1.0.2</version>
</dependency>
2,
@Api2Doc 注解详述
Api2Doc 一共有 3 个注解:@Api2Doc、@ApiComment 及 @ApiError 。
@Api2Doc 用于对文档的生成进行控制。
@Api2Doc 修饰在类上,表示这个类会参与到文档生成过程中,Api2Doc 服务
会扫描 Spring 容器中所有的 Controller 类,只有类上有 @Api2Doc 的类,
才会被生成文档,一个类对应于文档页面左侧的一级菜单项,@Api2Doc 的
name 属性则表示这个菜单项的名称。
@Api2Doc 也可以修饰在方法,不过在方法上的 @Api2Doc 通常是可以省略,
Api2Doc 服务会扫描这个类的所有带有 @RequestMapping 的方法,
每个这样的方法对应文档页面的左侧的二级菜单项, 菜单项的名称取
@RequestMapping 的 name 属性,当然您仍然可以在方法上用 @Api2Doc
的 name 属性进行重定义。
@ApiComment 注解详述
@ApiComment 用于对 API 进行说明,它可以修饰在很多地方:
- 修饰在类上,表示对这组 API 接口进行说明;
- 修饰在方法上,表示对这个 API 接口进行说明;
- 修饰在参数上,表示对这个 API 接口的请求参数进行说明;
- 修饰在返回类型的属性上,表示对这个 API 接口的返回字段进行说明;
- 修饰在枚举项上,表示对枚举项进行说明;
如果相同名称、相同意义的属性或参数字段,其说明已经在别的地方定义过了,
可以用 @ApiComment 的 seeClass 属性表示采用指定类的同名字段上的说明信息
@ApiComment(seeClass = User.class)
@ApiError 注解详述
@ApiError 用于定义错误码,有的 API 方法在执行业务逻辑时会产生错误,
出错后会在返回报文包含错误码,以方便客户端根据错误码作进一步的处理,
因此也需要在 API 文档上体现错误码的说明。
@ApiError 的 value 属性表示错误码,comment 表示错误码的说明。
可以用 @Api2Doc 中的 order 属性给菜单项排序,order 的值越小,
该菜单项就越排在前面.
Api2Doc生成 Restful API 文档的更多相关文章
- Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档
1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
- Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
- Golang使用swaggo自动生成Restful API文档
#关于Swaggo 相信很多程序猿和我一样不喜欢写API文档.写代码多舒服,写文档不仅要花费大量的时间,有时候还不能做到面面具全.但API文档是必不可少的,相信其重要性就不用我说了,一份含糊的文档甚至 ...
- 如何生成RestFul Api文档
Web API文档工具列表Swagger ——Swagger框架可以通过代码生成漂亮的在线API,甚至可以提供运行示例.支持Scala.Java.Javascript.Ruby.PHP甚至 Actio ...
- Spring Boot中使用Swagger2生成RESTful API文档(转)
效果如下图所示: 添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!-- https://mvnrepository.com/artifact/io.springfox ...
- Go学习笔记(六) | 使用swaggo自动生成Restful API文档(转)
关于Swaggo 或许你使用过Swagger, 而 swaggo就是代替了你手动编写yaml的部分.只要通过一个命令就可以将注释转换成文档,这让我们可以更加专注于代码. 目前swaggo主要实现了sw ...
- Swagger+Spring mvc生成Restful接口文档
简介 Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集 ...
- Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档
前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...
随机推荐
- web 安全相关(一):Log注入(转)
在网上有很多关于安全的文章,但是 OWASP 开发指导 涵 盖了几乎所有关于Web站点安全的东西.(注:OWASP(开放Web应用安全项目- Open Web Application Security ...
- free命令学习 输出理解
命令 [root@localhost ~]# free -m total used free shared buffers cached Mem: 7869 7651 218 1 191 5081 - ...
- linux环境下maven的安装配置
1.到官网下载maven,上传到服务器上 https://maven.apache.org/download.cgi 2.将压缩包上传服务器对应路径解压: tar -zxvf apache-maven ...
- 【转】MFC消息处理(一)
原文网址:http://blog.csdn.net/hyhnoproblem/article/details/6182120 1.MFC窗口如何与AfxWndProc建立联系. 当一个新的CWnd派生 ...
- winform 勾选可以改变框控件
public partial class UCCheck : UserControl { [Browsable(true), Category("修改属性"), Descripti ...
- TS流解析 三
应该说真正了解TS,还是看了朋友推荐的<数字电视业务信息及其编码>一书之后,MPEG2 TS和数字电视是紧密不可分割的,值得总结一下其中的一些关系. ISO/IEC-13818-1:系统部 ...
- 让多个Fragment 切换时不重新实例化
转自:http://www.yrom.net/blog/2013/03/10/fragment-switch-not-restart/ 让多个Fragment 切换时不重新实例化 在项目中需要进行Fr ...
- Django 组件-分页器
Django的分页器(paginator) view from django.shortcuts import render,HttpResponse # Create your views here ...
- mariadb master and salve configure
mariadb master and salve configure 主从复制配置: master:192.168.8.200 salve:192.168.8.201 主服务器配置: 主服务器需要启动 ...
- php去除换行符的方法小结(PHP_EOL变量的使用)
本来在unix世界换行就用/n来代替,但是windows为了体现他的不同,就用/r/n,更有意思的是在mac中用/r.因此unix系列用 /n,windows系列用 /r/n,mac用 /r,这样就用 ...