smart-doc在spring boot中的使用（替代swagger，无注入）

本文链接：https://blog.youkuaiyun.com/m0_73938805/article/details/144137823

参考文档

smart-doc Java Restful API 文档生成工具_smartdoc-优快云博客

Springboot 集成Smart-Doc生成接口文档（零注解）-优快云博客

自动生成接口文档、Smart-doc（Maven插件）使用教程 - Boblim - 博客园

我们随便找一个SpringBoot的项目就可以使用，所以非常方便。

接下来我就拿我自己的一个项目举例子。

这是我生成完后的大体框架，一个简单的springboot项目

为了使用smart-doc这个插件我们得先做好源代码的准备：

书写注解

如图所示，我们得向对应的controller总接口和分接口书写注解，注解的样式如图所示

/**
 * 点赞、收藏等行为控制器
 */


/**
 * 获取单个用户的对应博客的所有行为
 * @return
 * @param  blogId 博客ID
 * @param  openid 微信ID
 */

我们需要为每个controller书写相应的注解

之后我们还得去为每个实体类pojo书写相应的注解去确定表单

如下所示的代码

package com.example.blog_post.pojo;

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

/**
 * 行为表
 *
 * @author wuhan
 * @date 2024/11/29
 */
//使用@Data自动生成需要的get、set
@Data
//使用@AllArgsConstructor自动生成有参构造
@AllArgsConstructor
//使用@NoArgsConstructor自动生成无参构造
@NoArgsConstructor
public class Behavior {
    private Long id;
    private Long blogId;
    private String openid;
    private Boolean isFavorite;
    private Boolean isApproved;
    private Boolean isDisapproved;
}

这样我们就完成了源代码的准备了，之后我们需要去导依赖的需要的json串。

依赖pom.xml

        <dependency>
            <groupId>com.github.shalousun</groupId>
            <artifactId>smart-doc</artifactId>
            <version>1.1</version>
            <scope>test</scope>
        </dependency>

构建pom.xml

            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.4.8</version>
                <configuration>
                    <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <!--指定项目名称，推荐使用动态参数，例如${project.description}-->
                    <!--如果smart-doc.json中和此处都未设置projectName，2.3.4开始，插件自动采用pom中的projectName作为设置-->
                    <!--<projectName>${project.description}</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>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

之后我们需要去resource路径下去创建一个json文件叫smart-doc.json

{
  "serverUrl": "http://127.0.0.1:8080/api-demo/",
  "isStrict": false,
  "allInOne": true,
  "coverOld": true,
  "packageFilters": "",
  "outPath": "src/main/resources/static/doc",
  "md5EncryptedHtmlName": false,
  "projectName": "CMP基础服务API文档",
  "showAuthor":true,
  "dataDictionaries": [
    {
      "title": "状态字典",
      "enumClassName": "cn.xx.docStatusEnum",
      "codeField": "key",
      "descField": "value"
    }
  ]
}

创建完后我们便可以去maven里找到了