使用apiggs生成接口文档
与swagger的区别:
swagger就可以自动生成文档,但是swagger是侵入式的,和业务代码混在一起,而apiggs是一个非侵入式的maven插件,可以生成三种格式的文档:
html:api文档
json:可直接导入postman
adoc:一种asciidoc文档,可用文件处理器转换成其它格式文档,如html等
使用
添加pom依赖
<dependencies>
<!--API文档生成-->
<!--生成接口文档命令 mvn -DskipTests=true com.github.apiggs:apiggs-maven-plugin:1.6:apiggs-->
<dependency>
<groupId>com.github.apiggs</groupId>
<artifactId>apiggs-maven-plugin</artifactId>
<version>1.6</version>
</dependency>
</dependencies>
<plugin>
<groupId>com.github.apiggs</groupId>
<artifactId>apiggs-maven-plugin</artifactId>
<version>1.6</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>apiggs</goal>
</goals>
</execution>
</executions>
<!--以下配置可选-->
<configuration>
<id>api</id>
<title>API接口文档</title>
<dependency>../manage-domain/src/main/java</dependency>
<description>manage-core 文档</description>
<production>order</production>
<out>target/docs</out>
<version>1.0.1</version>
<description>
访问:http://127.0.0.1/api/order/[接口名]
非JSON格式传递的参数,请使用form-data的方式传值
默认所有接口请求头部(header)中加入如下参数
timestamp: 请求的当前时间戳,秒
sign: 进行MD5后的签名
</description>
</configuration>
</plugin>
<dependency>../manage-domain/src/main/java</dependency>是实体对象所在路径,当没有dependency内容时不会读取到返回的对象导致没有参数输出。
configuration配置说明:
id 项目id,生成的html文件名
title 文档标题
description 文档描述
production 输出文件夹,默认为 apiggs
out 输出目录,默认为 target
source 源码目录(1.6不支持该标签)
dependency 源码依赖的代码目录,以逗号隔开
jar 源码依赖的jar包目录,以逗号隔开
ignore 忽略某些类型
version 文档版本号
其中dependency中可以有多个依赖目录中间以,进行区分。
在启动类中添加@readme为目录的说明即为下面的文档说明内容,@index 2为第二个展示的目录,表示目录顺序Controller上面的注解说明为目录名称,Mapping请求上面的方法注释为方法的目录名称。
/**
* @readme 本项目的所有接口采用json 协议,为运营平台提供后台接口。
*/
@SpringBootApplication
@Configuration
@ComponentScan({"com.oppo.bot.common", "com.oppo.bot.manage"})
@MapperScan({"com.oppo.bot.manage.dal.mapper"})
@ImportResource(locations = { "classpath:applicationContext.xml","classpath:${dubbo.consumer.xml}"})
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
在类名上添加注释
/**
* 角色表 RoleController
*
* @author zhang
* @since 2017-11-13
*/
在方法上添加注释
/**
* 审核成功
*
* @param purc
* @param ptC
* @Author zhang
* @Date 2017/11/13 18:05
* @Return com.cqrk.grouptwo.common.Result
* @Exception
*/
生产的文档如下格式:
接口格式如下所示:index代表在文档中的顺序