最近需要设计一个API服务器，想要把API接口搞得规范一下，就通过网上搜集到了一些资料，以下便是自己的一些理解以及相关的具体实现
本文采用的是spring boot+maven的方案
restful规范这个规范我在这里也不打算长篇大论地讲解，怎么说呢，有人喜欢有人讨厌，我也不去争，因为我经验不多，看法和大佬有所不同。
restful规范简单来说，就是通过一些关键字去定义url接口，从而让url具有更好的可读性，如下面举个例子
# 查询所有用户 :9200/shunbang/api/user/users # 指定id为1的用户 :9200/shunbang/api/user/users/1 # 数据太多，只要前10 :9200/shunbang/api/user/users?limit=10 # 从第十条数据后开始（不要前十条数据） :9200/shunbang/api/user/users?offset=10我觉得restful规范起来，url的可读性较好
restful规范使用的几种方式
方式 说明get 从服务器上获取资源(select)
put 更新服务器上的资源(update)
post 将传入的资源存储在服务器上(insert)
delete 删除服务器上的资源(delete)
url请求协议介绍 方式 说明 例子
application/x-www-form-urlencoded 默认，客户端通过key-value键值对传递数据 :9200/shunbang/api/user/update?id=1&name=xx
application/json 客户端通过body发送json数据
application/xml 客户端通过body发送xml数据
application/octet-stream 客户端通过body发送Binary数据（二进制文件）
multipart/form-data 客户端通过body发送一个表单
API文档生成框架 smart-doc 介绍
这里，我使用了smart-doc这款框架，可以无侵入实现API接口的注释，需要在Controller和实体类中添加注释
使用此开源库很简单，我们只需要在maven项目中添加插件的依赖即可
<plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>1.0.2</version> <configuration> <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--> <configFile>./src/main/resources/smart-doc.json</configFile> <!--指定项目名称--> <projectName>测试</projectName> <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉--> <excludes> <!--格式为：groupId:artifactId;参考如下--> <exclude>com.alibaba:fastjson</exclude> </excludes> </configuration> <executions> <execution> <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉--> <phase>compile</phase> <goals> <goal>html</goal> </goals> </execution> </executions> </plugin>之后，在resources文件夹中新建smart-doc.json文件，进行一些配置即可
{ "outPath": "Q:\\JavaWebProject\\shunbang\\target", //指定文档的输出路径 "serverUrl": "http://localhost:9200/shunbang", //设置服务器地址,非必须 // "serverUrl": "http://47.101.148.199:9200/shunbang", //设置服务器地址,非必须 "isStrict": false, //是否开启严格模式 "allInOne": true //是否将文档合并到一个文件中，一般推荐为true }我这里没开启严格模式，若是开启了严格模式，则调用插件的时候就会报错
之后直接在旁边的插件找到，选择对应生成的文档
之后就可以在输出文件夹中找到html文件了
打开网页，就会有详细的文档了