关于java web restful api文档的从新探索

谁说生成api文档就必需要定义注解？
谁说生成接口请求和返回示例必需要在线？

用代码去探路，不断尝试更多文档交付的可能性。
若是代码有生命，为何不换种方式和它对话！

1、背景

没有背景、就本身作本身的背景

在当今各类盛行的先后端分离、restful service开发过程当中，接口文档是必不 可少的。对于先后端分离的开发中，后端开发须要将接口写好后须要告诉前端工程师接口的请求参数、响应示例等重要信息，而对于对外暴露的restful接口服务，咱们提供接口也是须要具有相同的接口文档的。

可是对于后端工程师来说，写接口文档将变成一个很大的工做量，虽然如今有相似apidoc、swagger这样的主流接口文档生成工具，可是若是实际用过，会发现这些工具不能知足实际需求，这里拿swagger为例，这个工具最大的优势能是提供在线的api文档，可是它天生就有很强的代码侵入性，要获得一个基本知足需求的api接口文档，必须在代码中使用swagger自定义的注解。这其实给开发人员增长学习成本和工做量，而且就算你使用大量的注解，有许多接口仍是没法知足。所以不得不去作一次接口文档工具从新启航探索，smart-doc应允而生，用代码去探路，消除繁杂的注解，发现天下没有难写的接口文档。

2、smart-doc简介

简约而不简单

smart-doc是基于java开发用于解决java web restful接口文档书写难和生成难的问题，固然api-doc也是一款零注解彻底基于源代码接口定义，使用java标准注释生成接口文档的工具。而且smart-doc代码也是彻底开源的。目前生成的文档格式为markdown。

smart-doc的码云仓库连接

github仓库地址连接

3、功能特性

一个都不能少

• 零注解、零学习成本、只须要写标准java注释。
• 基于源代码接口定义自动推导。
• 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
• 支持Callable,Future,CompletableFuture等异步接口返回的推导。
• 目前支持javabean上定义的部分fastjson和jackson注解。
• 支持javabean上基于jsr303参数检验判断参数是否为必须。
• 对json请求参数的接口可以自动生成模拟json参数。
• 对一些经常使用字段定义可以生成有效的模拟值。
• 支持生成json返回值示例。
• 支持从项目外部加载源代码来生成字段注释。
• 一款代码注释检测工具，明眼leader都知道接口文档直接反馈出注释状况。
• 支持生成静态的html格式api，轻易实如今Spring Boot服务上在线查看api文档。

4、效率成效

效率是作好工做的灵魂。——切斯特菲尔德

• 直接生成模拟请求参数，提高了团队里的前端和测试的工做效率，试想你让他们去编写json请求参数，若是你不写，鬼知道是什么样。
• 后端开发只需专一业务和写好标准注释，无需引入额外注解，无需本身编写请求参数示例和响应示例。
• 接口文档更加标准化

5、缺点

只有看到本身的不足，才能得到进步。

• 因为基于源代码分析生成文档，所以没法生成在线文档，须要结合地方markdown文档管理工具来管理。
• 因为源代码分析难度很大，针对不少代码存在潜在的大量的bug.
• 对泛型返回接口须要明肯定义泛型定义，不然没法推导

6、用例

<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>1.7.5</version>
</dependency>

6.1 定义bean

/**
 * @author yu 2018/8/4.
 */
public class SimpleUser {

    /**
     * 用户名
     */
    @NotNull
    private String username;

    /**
     * 密码
     */
    private String password;

    /**
     * 昵称
     */
    private String nickName;

    /**
     * 电话
     */
    private String mobile;

}

6.2 定义接口

/**
 * 用户信息操做接口
 * @author yu 2018/8/4.
 */

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 添加用户
     * @param user
     * @return
     */
    @PostMapping("/add")
    public List<SimpleUser> addUser(@RequestBody SimpleUser user){
        return null;
    }
}

启动文档生成

/**
 * 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
 */
@Test
public void testBuilderControllersApi() {
    ApiConfig config = new ApiConfig();
    config.setServerUrl("http://localhost:8080");
    config.setStrict(true);
    config.setOutPath("d:\\md");
    //不指定SourceCodePaths默认加载代码为项目src/main/java下的,若是项目的某一些实体来自外部代码能够一块儿加载
    config.setSourceCodePaths(
            SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java")

           //  SourceCodePath.path().setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java"),
           // SourceCodePath.path().setDesc("加载项目外代码").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
    );

    long start = System.currentTimeMillis();
    ApiDocBuilder.builderControllersApi(config);
    long end = System.currentTimeMillis();
    DateTimeUtil.printRunTime(end, start);
}

生成文档

添加用户

URL: http://localhost:8080/user/add

Type: post

Content-Type: application/json; charset=utf-8

Request-parameters:

Parameter	Type	Description	Required
username	string	用户名	true
password	string	密码	false
nickName	string	昵称	false
mobile	string	电话	false

Request-example:

{
	"username":"瑞霖.张",
	"password":"xud2qc",
	"nickName":"rudy.goyette",
	"mobile":"15650966307"
}

Response-fields:

Field	Type	Description
username	string	用户名
password	string	密码
nickName	string	昵称
mobile	string	电话

Response-example:

[
	{
		"username":"浩然.阎",
		"password":"dzlv56",
		"nickName":"kieran.herzog",
		"mobile":"17863739656"
	}
]

demo地址：https://github.com/shalousun/api-doc-test

7、将来定义

期待下一次咱们更好的相遇

• 修改源代码解析的众多的bug
• 收集使用者的建议，提供非json请求参数的请求示例
• 收集使用者一些新增功能建议，增长一些必须功能。

8、使用协议

尊重别人，才能让人尊敬。——笛卡尔

• 任何企业和我的不得用于申请专利

9、使用反馈

分享是一种生活的信念，明白了分享的同时，明白了存在的意义。

smart-doc的发展离不开你的支持，由于出于彻底的开源免费，所以您能够基于smart-doc的源码解析核心上去作一些自定义的开发来将接口文档数据接入到一些第三方的在线api文档管理系统，例如：CrapApi，可是在请使用者能有一份开源的心态和情怀，积极反馈api-doc的核心代码使用bug和提出改善意见。<br/> 因为我我的的开发精力有限，对因而否会将smart-doc快速集成推送到第三方优秀的管理工具，短时间内可能不会考虑，所以也但愿使用者分享一些比较好的集成方案来供你们使用，若是方案比较符合smart-doc使用简洁的核心理念，将会直接归入后续的版本升级中，同时源代码和方案提供者也将归入smart-doc的开发者。

10、祝福

愿你编写接口无数，归来还是少年

ps:转载请注明https://my.oschina.net/u/1760791/blog/write/1931071