本文档讲述单个SpringBoot项目集成smart-doc的流程

1 下载代码编译

源码地址：

修改私服地址，mvn deploy到私服

<distributionManagement>
    <repository>
        <id>local</id>
        <name>releases</name>
        <url>http://xxx.xxx.xxx.xxx:8081/repository/releases/</url>
    </repository>
    <snapshotRepository>
        <id>local</id>
        <name>snapshots</name>
        <url>http://xxx.xxx.xxx.xxx:8081/repository/snapshots/</url>
    </snapshotRepository>
</distributionManagement>

2 创建SpringBoot Demo项目

1. 创建Maven项目
2. 修改pom文件，改为springboot项目

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.0</version>
</parent>

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

3 项目代码

package com.doc.test;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * 测试类
 * 
 * @author young
 * @since 2021-04-29
 *
 */
@RestController
@RequestMapping("/test")
public class TestController {

    /**
     * 测试方法1
     * 
     * @param test
     * @return
     */
    @RequestMapping(value = "req-test", method = RequestMethod.GET)
    public BaseRespVO<TestRespVO> reqTest(String test) {
        BaseRespVO<TestRespVO> respVO = new BaseRespVO<>();
        return respVO;
    }
    
    /**
     * 测试方法2    
     * 
     * @param reqVO
     * @return
     */
    
    @RequestMapping(value = "resp-test", method = RequestMethod.POST)
    public BaseRespVO<Void> respTest(TestReqVO reqVO) {
        BaseRespVO<Void> respVO = new BaseRespVO<>();
        return respVO;
    }

}

package com.doc.test;

public class TestReqVO {
    /**
     * 国家
     */
    private String country;
    /**
     * 省
     */
    private String province;
    /**
     * 市
     */
    private String city;
    /**
     * 姓名
     */
    private String name;
    /**
     * 年龄
     * 
     */
    private int age;

    public String getCountry() {
        return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }

    public String getProvince() {
        return province;
    }

    public void setProvince(String province) {
        this.province = province;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

}

package com.doc.test;

public class TestRespVO {
    /**
     * 唯一id
     */
    private int id;
    /**
     * 随机码uuid
     * 
     */
    private String uuid;
    
    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public String getUuid() {
        return uuid;
    }
    public void setUuid(String uuid) {
        this.uuid = uuid;
    }
    
}

package com.doc.test;

/**
 * 返回数据Base对象
 */
public class BaseRespVO<T> {

    /**
     * 返回码
     * 
     */
    private int code = 0;
    /**
     * 返回码描述信息
     * 
     */
    private String desc;
    /**
     * 返回数据
     * 
     */
    protected T data;

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getDesc() {
        return desc;
    }

    public void setDesc(String desc) {
        this.desc = desc;
    }

    @Override
    public String toString() {
        return super.toString();
    }
}

4 配置smart-doc

/src/main/resource目录下创建smart-doc.json文件

{
   "outPath": "E:\\apidoc" 
}

Pom文件增加plugin配置

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.4.6</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中 -->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称 -->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉 -->
        <excludes>
            <!--格式为：groupId:artifactId;参考如下 -->
            <!--也可以支持正则式如：com.alibaba:.* -->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意 -->
        <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件 -->
        <includes>
            <!--格式为：groupId:artifactId;参考如下 -->
            <!--也可以支持正则式如：com.alibaba:.* -->
            <include>com.alibaba:fastjson</include>
            <!-- 如果配置了includes的情况下， 使用了mybatis-plus的分页需要include所使用的源码包 -->
            <include>com.baomidou:mybatis-plus-extension</include>
            <!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 -->
            <include>org.springframework.data:spring-data-commons</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉 -->
            <phase>compile</phase>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置 -->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

maven编译-Dfile.encoding=UTF-8 smart-doc:html

5 结果预览

结果预览.png

SpringBoot多模块项目集成smart-doc详见springboot快速集成smart-doc生成文档(二)。