02 Idea配置Smart-Doc插件进行接口发布

一、依赖配置

根POM文件中增加Smart-Doc插件的配置，节点位置：Project-build-pluginManagement-plugins

<plugin>
    <groupId>com.github.shalousungroupId>
    <artifactId>smart-doc-maven-pluginartifactId>
    <version>${smart-doc.version}version>
    <configuration>
        
        <configFile>src/main/resources/smart-doc.jsonconfigFile>
        
        <projectName>${project.description}projectName>
    configuration>
    <executions>
        <execution>
            
            <phase>compilephase>
            
            <goals>
                

            goals>
        execution>
    executions>
plugin>

• 注意**“configFile”**节点，此节点配置了smart-doc插件的生成配置文件（json）。后续各个业务模块中需要增加同名配置文件，位于业务模块中src/main/resource目录中

二、服务模块中增加smart-doc.json配置文件

此项配置参考官方文档以及atearth-cloud项目中的配置，整体流程如下：

• Torna界面创建空间
• Torna界面，进入空间，创建项目
• Torna界面，进入项目，创建模块
• Torna界面，进入模块，打开OpenAPI标签页，获取到Torna请求途径以及Token

• IDEA，业务模块resource目录增加smart-doc.json配置文件
• IDEA，配置文件中参考项目代码以及项目信息更新smart-doc.json配置文件，可采用下列模板

{
  "serverUrl": "http://127.0.0.1:port/gateway", # 服务请求路径
  "isStrict": false,
  "allInOne": true,
  "outPath": "src/main/resources/static/doc", # 接口文档的输出目录
  "coverOld": true,
  "createDebugPage": true,
  "style": "xt256",
  "packageFilters": "com.xxx.xxx.xxx.controller.*", # 包过滤器
  "appToken": "a830e52d0f514ee08136a1d42e09209d", # 创建模块后模块OpenAPI标签页中的Token
  "openUrl": "http://tornaIp:tornaPort/api", # 创建模块后模块OpenAPI标签页中的请求路径（Torna的请求路径）
  "md5EncryptedHtmlName": true,
  "projectName": "项目描述信息",
  "tornaDebug": true,
  "inlineEnum": true,
  "skipTransientField": true,
  # 错误代码字典，此项指向了错误代码枚举类，如果没有对应错误代码（枚举类），删除此段即可
  "errorCodeDictionaries": [
    {
      "title": "title",
      "enumClassName": "com.xxx.result.CommonCodeEnum",
      "codeField": "code",
      "descField": "message"
    }
  ],
  "revisionLogs": [
    {
      "version": "1.0.0",
      "revisionTime": "2022-10-12 17:30",
      "status": "create",
      "author": "作者",
      "remarks": "模块标签"
    }
  ],
  "requestHeaders": [
    {
      "name": "Authorization",
      "type": "string",
      "desc": "Oauth2 权限请求头",
      "value": "Bearer ",
      "required": false,
      "since": "1.0.0"
    }
  ]
}

三、接口发布

IDEA -> 右侧Maven界面 -> 指定项目 -> Plugins -> smart-doc ->双击smart-doc:torna-rest插件按钮进行发布

四、参考文档

smart-doc配置官方文档：此文档为官方文档，说明较详细
@ignoreParams使用
Spring MVC can’t support binding Collection on method importUser,Check it in com.qgs.admin.controller.SysUserController

五、其他

1、Smart-Doc推送接口文档时@RequestParameter被解析到了BodyParameters中怎么办？

此环节属于smart-doc解析文档时的问题，可尝试将smart-doc插件升级到最新版本后尝试解决。

2、确保服务正常启用，但Torna在线调试接口时不时会出现连接超时的问题怎么办？

此问题尚未解决，后续解决会补充。

3、Spring MVC can’t support binding Collection on method importUser,Check it in com.qgs.admin.controller.SysUserController 推送接口时出现此异常怎么办？

此情况往往出现在接口参数为非Json参数List。参考一下作者的解答：

issue：Spring MVC can’t support binding Collection on method importUser,Check it in com.qgs.admin.controller.SysUserController