API-DOC

介绍

api-doc是一个文档自动生成的工具，致力于减轻程序员撰写文档的烦恼。自动化配置，完美融合SpringBoot框架，可在线预览文档，也可以下载markdown格式的文档，后期慢慢加入在线调试的功能。

使用

api-doc的使用非常简单，与SpringBoot无缝集成。只需在spring的配置文件application.properties配置应用几个基本信息即可。

第一步：引入maven依赖

1、使用maven从源码安装

clone项目代码

git clone https://github.com/iloveruning/api-doc.git

进入项目

cd api-doc

安装到本地仓库

mvn clean install

2、在pom.xml中添加依赖

 <dependency>
<groupId>io.github.llchen</groupId>
<artifactId>api-doc</artifactId>
<version>0.1.0</version>
</dependency>

第二步：修改配置文件 application.properties

第三步：具体使用

在controller类上中使用注解@ApiDoc，在方法上使用注解@Api。

@ApiDoc(name = "用户接口API", description = "用户接口API描述", version = "1.0.0",
codes = {@ApiCode(code = "200", description = "success"), @ApiCode(code = "400", description = "fail")})
@Controller@RequestMapping("/user")
publicclassUserController {
privatestaticConcurrentHashMap<String, User> userMap = newConcurrentHashMap<>();
privatestaticAtomicIntegeridCount=newAtomicInteger(0);
@Api(description = "通过id获取用户信息",
requestParams = {@ApiParam(name = "id", description = "用户id", required = true)},
demoResponse = "{\n" +
"\"name\": \"llchen12\",\n" +
"\"age\": 12,\n" +
"\"id\": \"123\",\n" +
"\"email\": \"3304734570@qq.com\"\n" +
"}",
resultModel = User.class,remark = "这是备注")
@GetMapping("/{id}")
publicUsergetUserById(@PathVariable("id") Stringid) {
returnuserMap.get(id);
}
@Api(description = "添加用户",demoResponse = "{ \"id\": 1, \"name\": \"llchen12\", \"age\": 21, \"email\": \"3304734570@qq.com\" }")
@PostMapping("/add")
publicUseraddUser(@RequestBodyUseruser){
user.setId(String.valueOf(idCount.incrementAndGet()));
userMap.put(user.getId(),user);
returnuser;
}
}

在model类上中使用注解@ApiModel，在属性上使用注解@ApiModelProperty。

@Data@ApiModel(description = "用户表model")
publicclassUser {
@ApiModelProperty(name = "id",description = "用户id",required = true)
privateStringid;
@ApiModelProperty(name = "username",description = "用户名",required = true)
privateStringusername;
@ApiModelProperty(name = "password",description = "密码",required = true)
privateStringpassword;
@ApiModelProperty(name = "age",description = "年龄",required = false,type = DataType.INT)
privateIntegerage;
@ApiModelProperty(name = "email",description = "邮箱",required = true)
privateStringemail;
}

完成以上步骤后，我们就可以启动应用啦！

这时候可以访问http://host:port/api/html，会看到生成的api文档预览页面

访问http://host:port/api/markdown，可以下载markdown格式的文档

注解详细介绍

共有6个注解，标注整个文档信息。

• ApiDoc 标注API文档的基本信息
• Api 描述某一个api
• ApiParam 请求和响应的参数描述
• ApiCode 响应码（错误码）描述
• ApiModel 数据字典（model）描述
• ApiModelProperty model属性描述

详细介绍如下

@ApiDoc:写在类上，表示这是一个API文档 属性：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inheritedpublic @interface ApiDoc {
/** *文档名称 */Stringname();
/** * api描述 */Stringdescription() default"";
/** *api基本path */StringbasePath() default"";
/** *文档版本 */Stringversion() default"";
/** * 响应码 */ApiCode[] codes() default {};
}

@Api:写在方法上，描述一个具体接口的信息 属性：

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documentedpublic @interface Api {
/** *接口名字 */Stringname() default"";
/** *请求URL */Stringpath() default"";
/** * 描述 */Stringdescription() default"";
/** * 备注 */Stringremark() default"";
/** * http请求方式 */String[] httpMethod() default {};
/** * 请求参数 */ApiParam[] requestParams() default {};
/** *返回示例 */StringdemoResponse() default"";
/** * 返回参数 */ApiParam[] responseParams() default {};
/** *返回值模型 */Class<?> resultModel() defaultVoid.class;
}

@ApiParam: 写在注解内,描述请求和响应的参数 属性：

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
@Documentedpublic @interface ApiParam {
/** * 参数名 */Stringname();
/** * 参数说明 */Stringdescription();
/** * 默认值 */StringdefaultValue() default"";
/** * 是否必选 */booleanrequired() defaultfalse;
/** * 示例 */Stringexample() default"";
/** * 数据类型 */DataTypetype() defaultDataType.STRING;
}

@ApiCode: 写在注解内，描述响应码 属性：

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Inheritedpublic @interface ApiCode {
/** * 错误码 */Stringcode();
/** * 错误解释 */Stringdescription();
}

@ApiModel: 写在类上，描述一个model的基本信息 属性：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inheritedpublic @interface ApiModel {
/** * 数据模型描述 */Stringdescription() default"";
/** * 备注 */Stringremark() default"";
}

@ApiModelProperty: 写在属性上，描述model属性的信息 属性：

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
@Documentedpublic @interface ApiModelProperty {
/** * 参数名 */Stringname();
/** * 参数说明 */Stringdescription();
/** * 默认值 */StringdefaultValue() default"";
/** * 是否必选 */booleanrequired() defaultfalse;
/** * 示例 */Stringexample() default"";
/** * 数据类型 */DataTypetype() defaultDataType.STRING;
}

支持和反馈

由于每个人写代码的习惯可能都不一样，虽然已经尽可能考虑到了多种不同的情况，但由于作者本人的认知和精力有限，难免会疏忽或者本身就存在有 bug 的情况，如果你在使用的过程中有碰到困难或者疑问，欢迎提issue

如果你觉得这个项目对你有用，不妨给个⭐star。

你的支持是我前进的动力！