api文档生成工具apiggs的使用

代码即文档

Apiggs是一个非侵入的RestDoc文档生成工具。工具通过分析代码和注释，获取文档信息，生成RestDoc文档。

首先需要在pom中添加apiggs的依赖依赖，<dependency>../bot-manage-domain/src/main/java</dependency>是实体对象所在路径，当没有dependency内容时不会读取到返回的对象导致没有参数输出。
    <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>  

//里面都是一些options包括id，title等以下内容。

//返回对象和请求参数所在的目录，如果不加则生成的这些接口没有这些实体参数        
    <dependency>../bot-manage-domain/src/main/java</dependency>      
    <description>bot-manage-core 文档2222</description>        
    <version>2.0</version>     
    </configuration> 
    </plugin>

 

在<configuration>之间添加<dependency>../bot-manage-domain/src/main/java</dependency> <description>bot-manage-core 文档</description> <version>1.0</version> </configuration> 

其中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);
   }

生产的文档如下格式：

**

接口格式如下所示：index代表在文档中的顺序

apiggs的git地址为：https://github.com/apigcc/apigcc-maven-plugin

configuration里面的标签以及说明如下：

 

options

1. id 项目id，生成id.html文件
2. title 文档标题
3. description 文档描述
4. production 输出文件夹，默认为 apiggs
5. out 输出目录，默认为 target
6. source 源码目录
7. dependency 源码依赖的代码目录，以逗号隔开
8. jar 源码依赖的jar包目录，以逗号隔开
9. ignore 忽略某些类型
10. version 文档版本号

 * @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}"})
@EnableTransactionManagement
public class Application {

   public static void main(String[] args) {
      SpringApplication.run(Application.class, args);
   }