1 Star 0 Fork 3

虹舞长空 / smart-doc-gradle-plugin

加入 Gitee
与超过 600 万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
README.md 13.20 KB
一键复制 编辑 Web IDE 原始数据 按行查看 历史
上官胡闹 提交于 2021-04-25 22:09 . release 2.1.4

Smart-Doc Gradle Plugin

maven License number of issues closed closed pull requests java version chinese

Introduce

smart-doc-gradle-plugin is a gradle plugin developed by the smart-doc official team. This plugin is available from smart-doc 1.8.6. Using smart-doc-gradle-plugin makes it easier to integrate smart-doc into your project, and integration is more lightweight. You no longer need to write unit tests in your project to Start smart-doc to scan source code analysis and generate API documents. You can run the gradle command directly or click on the preset goal of the smart-doc-maven-plugin in the IDE to generate API documentation. smart-doc-gradle-plugin will also make smart-doc's ability to generate API documentation more powerful. About smart-doc

Best Practice

smart-doc + Torna form an industry-leading document generation and management solution, using smart-doc to complete Java source code analysis and extract annotations to generate API documents without intrusion, and automatically push the documents to the Torna enterprise-level interface document management platform.

smart-doc+torna

Getting started

Add plugin

Using the plugins DSL:

plugins {
  id "com.github.shalousun.smart-doc" version "[latest]"
}

Using legacy plugin application:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "com.github.shalousun:smart-doc-gradle-plugin:[latest]"
  }
}

apply plugin: "com.github.shalousun.smart-doc"

Plugin options

Option Default value Description
configFile src/main/resources/default.json
exclude exclude artifact,usage:exclude 'org.springframework.boot:spring-boot-starter-tomcat'
include Let the plugin download the specified java lib source,usage:include 'org.springframework.boot:spring-boot-starter-tomcat'

Example setting of options:

smartdoc {
    configFile = file("src/main/resources/default.json")
    
    // exclude example
    // exclude artifact
    exclude 'org.springframework.boot:spring-boot-starter-tomcat'
    // exclude artifact use pattern
    exclude 'org.springframework.boot.*'
    // You can use the include configuration to let the plugin automatically load the specified source.
    // include example
    include 'org.springframework.boot:spring-boot-starter-tomcat'
}

For multi-module gradle projects, if you do not want to configure in each module, you can put the smart-doc plugin related configuration into subprojects.

subprojects{
    apply plugin: 'com.github.shalousun.smart-doc'
    smartdoc {
        //
        configFile = file("src/main/resources/smart-doc.json")
        // exclude artifact
        exclude 'org.springframework.boot:xx'
        exclude 'org.springframework.boot:ddd'
        // You can use the include configuration to let the plugin automatically load the specified source.
        // include example
        include 'org.springframework.boot:spring-boot-starter-tomcat'
    }
}

Create a json config

Create a json configuration file in your project. If it is multiple modules, put them in the modules that need to generate documents. The smart-doc-gradle-plugin plugin will use this configuration information. For example, create /src/main/resources/smart-doc.json in the project. The configuration contents are as follows.

Minimize configuration:

{
   "allInOne": true, // whether to merge documents into one file, generally recommended as true
   "isStrict": false,//If the strict mode is set to true, Smart-doc forces that the public method in each interface in the code has a comment.
   "outPath": "/src/main/resources" //Set the api document output path.
}

Only three configuration items are required to use the smart-doc-gradle-plugin to generate API documentation. In fact, only outPath must be configured.

Detailed configuration content:

When you need to use smart-doc to generate more API document information, you can add detailed configuration content.

{
  "serverUrl": "http://127.0.0.1", // Set the server address, not required
  "isStrict": false, // whether to enable strict mode
  "allInOne": true, // whether to merge documents into one file, generally recommended as true
  "outPath": "D: // md2", // Specify the output path of the document
  "coverOld": true, // Whether to overwrite old files, mainly used for mardown file overwrite
  "style":"xt256", //set highlight
  "createDebugPage": true,//Create a page that can be used to test your APIs like swagger
  "language":"ENGLISH",//support ENGLISH and CHINESE
  "packageFilters": "", // controller package filtering, multiple package names separated by commas
  "md5EncryptedHtmlName": false, // only used if each controller generates an html file
  "projectName": "smart-doc", // Configure your own project name
  "skipTransientField": true, // Not currently implemented
  "requestFieldToUnderline":true, //convert request field to underline
  "responseFieldToUnderline":true,//convert response field to underline
  "sortByTitle":false,//Sort by interface title, the default value is false
  "showAuthor":true,// display author,default is true
  "inlineEnum":true,// Set to true to display enumeration details in the parameter table
  "recursionLimit":7,// Set the number of recursive executions to avoid stack overflow, the default is 7
  "allInOneDocFileName":"index.html",//Customize the output document name
  "requestExample":"true",//Whether to display the request example in the document, the default value is true.
  "responseExample":"true",//Whether to display the response example in the document, the default is true.
  "displayActualType":false,//display actual type of generic,
  "urlSuffix":".do",//Support the url suffix of the old SpringMVC project,@since 2.1.0
  "appKey": "xxx",// torna appKey, @since 2.0.9
  "appToken": "xxx", //torna appToken,@since 2.0.9
  "secret": "xx",//torna secret,@since 2.0.9
  "openUrl": "torna server/api/",//torna server url,@since 2.0.9
  "ignoreRequestParams":[ //The request parameter object will be discarded when generating the document.@since 1.9.2
       "org.springframework.ui.ModelMap"
  ],
  "dataDictionaries": [{// Configure the data dictionary, no need to set
       "title": "Order Status", // The name of the data dictionary
       "enumClassName": "com.power.doc.enums.OrderEnum", // Data dictionary enumeration class name
       "codeField": "code", // The field name corresponding to the data dictionary dictionary code
       "descField": "desc" // Data dictionary object description information dictionary
  }],
  "errorCodeDictionaries": [{// error code list, no need to set
       "title": "title",
       "enumClassName": "com.power.doc.enums.ErrorCodeEnum", // Error code enumeration class
       "codeField": "code", // Code field name of the error code
       "descField": "desc" // Field name corresponding to the error code description
  }],
  "revisionLogs": [{// Set document change records, no need to set
       "version": "1.0", // Document version number
       "revisionTime": "2020-12-31 10:30", //revision time
       "author": "author", // Document change author
       "status": "update", // Change operation status, generally: create, update, etc.
       "remarks": "desc" // Change description
  }],
  "customResponseFields": [{// Customly add fields and comments. If api-doc encounters a field with the same name later, directly add a comment to the corresponding field. It is not necessary.
       "name": "code", // Override the response code field
       "desc": "Response code", // Override field comment of response code
       "value": "00000" // Set the value of the response code
  }],
  "customRequestFields": [{//@since 2.1.3
       "name":"code", //Override the request code field
       "desc":"request code", //Override field comment of response code
       "ownerClassName":"com.xxx.constant.entity.Result",
       "value":"200", // Set the value of the response code
       "required":true,
       "ignore":false
  }],
  "apiObjectReplacements": [{ // Supports replacing specified objects with custom objects to complete document rendering
       "className": "org.springframework.data.domain.Pageable",
       "replacementClassName": "com.power.doc.model.PageRequestDto" //Use custom PageRequestDto instead of JPA Pageable for document rendering.
  }],
  "rpcApiDependencies":[{ // Your Apache Dubbo api interface module dependency description.
       "artifactId":"SpringBoot2-Dubbo-Api",
       "groupId":"com.demo",
       "version":"1.0.0"
  }],
  "apiConstants": [{//Configure your own constant class, smart-doc automatically replaces with a specific value when parsing to a constant
       "constantsClassName": "com.power.doc.constants.RequestParamConstant"
   }],
  "responseBodyAdvice":{ //Support ResponseBodyAdvice
       "className":"com.power.common.model.CommonResult" // Standard POJO for Response
  },
  "requestBodyAdvice":{ //Support ResponseBodyAdvice
       "className":"com.power.common.model.CommonResult" // Standard POJO for Request
  },
  "rpcConsumerConfig": "src/main/resources/consumer-example.conf",//dubbo consumer config example
  "requestHeaders": [{// Set global request headers, no need to set
       "name": "token",
       "type": "string",
       "desc": "desc",
       "required": false,
       "since": "-"
  }]
}

Note: The above json configuration is completely converted into json using the smart-doc's ApiConfig. So the project configuration can also refer to the introduction of smart-doc.

Generated document

Use Gradle command

// Generate html
gradle smartDocRestHtml
// Generate markdown
gradle smartDocRestMarkdown
// Generate adoc
gradle smartDocRestAdoc
// Generate postman collection
gradle smartDocPostman
// Generate Open Api 3.0+
gradle smartDocOpenApi
// Generate document and send to Torna
gradle tornaRest

// For Apache Dubbo Rpc
gradle smartDocRpcHtml
// Generate markdown
gradle smartDocRpcMarkdown
// Generate adoc
gradle smartDocRpcAdoc

Use In IntelliJ IDEA

On Use IntelliJ IDE, if you have added smart-doc-gradle-plugin to the project, you can directly find the plugin smart-doc plugin and click to generate API documentation.

smart-doc-gradle-plugin

Generated document example

Interface header rendering

header

Request parameter example rendering

request-params

Response parameter example renderings

response-fields

Building

you can build with the following commands. (Java 1.8 is required to build the master branch)

// build and publish to local
gradle publishToMavenLocal
// build and publish to nexus
gradle uploadArchives

Other reference

Who is using

These are only part of the companies using smart-doc, for reference only. If you are using smart-doc, please add your company here to tell us your scenario to make smart-doc better.

iFLYTEK         

License

smart-doc-gradle-plugin is under the Apache 2.0 license. See the LICENSE file for details.

Contact

Email: 836575280@qq.com

Java
1
https://gitee.com/hwck/smart-doc-gradle-plugin.git
git@gitee.com:hwck/smart-doc-gradle-plugin.git
hwck
smart-doc-gradle-plugin
smart-doc-gradle-plugin
master

搜索帮助