smart-doc+Torna自动生成Java Api接口文档

smart-doc (opens new window)+ Torna 组成行业领先的文档生成和管理解决方案，使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

前提条件: 已经安装部署了Torna

pom.xml

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>web-parent</artifactId>
        <groupId>com.test</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>smart-doc-torna</artifactId>
    <name>smart-doc-torna</name>
    <description>测试smart-doc</description>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <build>
        <finalName>SmartDoc-Torna</finalName>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${springboot.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>

            <plugin>
                <groupId>com.ly.smart-doc</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>${smart.doc.version}</version>
                <configuration>
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <projectName>${project.description}</projectName>
                    <includes>
                        <!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 -->
                        <include>com.baomidou:mybatis-plus-extension</include>
                        <!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core-->
                        <!--                        <include>com.baomidou:mybatis-plus-core</include>-->
                        <!-- 使用了jpa的分页需要include所使用的源码包 -->
                        <!--                        <include>org.springframework.data:spring-data-commons</include>-->
                    </includes>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>package</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

application.yaml

spring:
  application:
    name: SmartDoc-Torna

server:
  servlet:
    context-path: /SmartDoc-Torna
  port: 8891

smart-doc.json

{
  "serverUrl": "http://127.0.0.1:8891",
  "outPath": "./src/main/resources/static/doc",
  "projectName": "webtest",
  "packageFilters": "com.test.controller.*",
  "openUrl": "http://127.0.0.1:7700/api",
  "appToken": "4eb03e4381544272815630ea123456",
  "allInOne": true,
  "createDebugPage": true,
  "debugEnvName":"本地环境",
  "debugEnvUrl":"http://127.0.0.1:8891/SmartDoc-Torna",
  "tornaDebug": true,
  "replace": true
}

PeopleDTO

package com.test.bean;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class PeopleDTO {

    /**
     * 名称
     * @mock 张三
     */
    private String name;

    /**
     * 年龄
     * @mock 100
     */
    private int age;
}

TestController

package com.test.controller;

import com.test.bean.PeopleDTO;
import org.springframework.web.bind.annotation.*;

/**
 * test控制类
 */
@RequestMapping("/test")
@RestController
public class TestController {

    /**
     * 查询数据
     * @param name 名称|abc
     * @param age 年龄|10
     * @return PeopleDTO
     */
    @GetMapping("/getPeople")
    public PeopleDTO getPeople(@RequestParam String name, @RequestParam int age) {
        return new PeopleDTO(name, age);
    }


    /**
     * 保存数据
     * @return PeopleDTO
     */
    @PostMapping("/savePeople")
    public PeopleDTO savePeople(@RequestBody PeopleDTO peopleDTO) {
        return peopleDTO;
    }
}