1 Star 0 Fork 161

tkmeeta / smart-doc

forked from smart-doc-team / smart-doc 
Create your Gitee Account
Explore and code with more than 5 million developers,Free private repositories !:)
Sign up
Clone or download
Cancel
Notice: Creating folder will generate an empty file .keep, because not support in Git
Loading...
README.md

Smart-Doc Project

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

Introduce

smart-doc is a tool that supports both JAVA REST API and Apache Dubbo RPC interface document generation. Smart-doc is based on interface source code analysis to generate interface documents, and zero annotation intrusion. You only need to write Javadoc comments when developing, smart-doc can help you generate Markdown or HTML5 document. smart-doc does not need to inject annotations into the code like Swagger.

Features

  • Zero annotation, zero learning cost, only need to write standard JAVA document comments.
  • Automatic derivation based on source code interface definition, powerful return structure derivation support.
  • Support Spring MVC, Spring Boot, Spring Boot Web Flux (Not support endpoint), Feign.
  • Supports the derivation of asynchronous interface returns such as Callable, Future, CompletableFuture.
  • Support JSR-303 parameter verification specification.
  • Support for automatic generation of request examples based on request parameters.
  • Support for generating JSON return value examples.
  • Support for loading source code from outside the project to generate field comments (including the sources jar package).
  • Support for generating multiple formats of documents: Markdown,HTML5,Asciidoctor,Postman Collection,OpenAPI 3.0.
  • Support for exporting error codes and data dictionary codes to API documentation.
  • Support Apache Dubbo RPC.

Getting Started

Smart-doc Samples

# git clone https://github.com/shalousun/smart-doc-demo.git

This example already provides a static html document generated in advance. You can start the Spring Boot project and then go directly to http://localhost:8080/doc/api.html to view the interface documentation generated by smart-doc. Of course, you can also browse http://localhost:8080/doc/api.html, which looks a html like generated by asciidoctor-maven-plugin plugin.

Add Maven Plugin

Add smart-doc-maven-plugin in your pom.xml.

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[latest]</version>
    <configuration>
        <!--Specify the configuration file used to generate the document-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--smart-doc implements automatic analysis of the dependency tree to load the source code of third-party dependencies. If some framework dependency libraries are not loaded, an error is reported, then use excludes to exclude-->
        <excludes>
            <!--The format is: groupId: artifactId; refer to the following-->
            <exclude>com.google.guava:guava</exclude>
        </excludes>
        <!--Since version 1.0.8, the plugin provides includes support-->
        <!--smart-doc can automatically analyze the dependency tree to load all dependent source code. In principle, it will affect the efficiency of document construction, so you can use includes to let the plugin load the components you configure.-->
        <includes>
            <!--The format is: groupId: artifactId; refer to the following-->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--Comment out phase if you don't need to start smart-doc when compiling-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Configuration

Create a JSON configuration file in your project. The smart-doc-maven-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 the above three simple configuration items can make smart-doc-maven-plugin work. In fact, only the outPath configuration item is necessary.

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
  "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
  "sortByTitle":false,//Sort by interface title, the default value is false
  "requestFieldToUnderline":true, //convert request field to underline
  "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
  "responseFieldToUnderline":true,//convert response field to underline
  "allInOneDocFileName":"index.html",//Customize the output document name
  "displayActualType":false,//display actual type of generic,
  "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.
  "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
      "status": "update", // Change operation status, generally: create, update, etc.
      "author": "author", // Document change author
      "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
    }
  ],
  "rpcApiDependencies":[{ //Your dubbo api denpendency
        "artifactId":"SpringBoot2-Dubbo-Api",
        "groupId":"com.demo",
        "version":"1.0.0"
  }],
  "rpcConsumerConfig": "src/main/resources/consumer-example.conf",//dubbo consumer config example
  "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.
  }],
  "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"
  }],
  "requestHeaders": [// Set global request headers, no need to set
    {
      "name": "token",//header name
      "type": "string",//header type
      "desc": "description of this header.",
      "required": false,
                        "value":"your header value",
      "since": "-"
    }
  ]
}

Note: This JSON configuration can be converted into JSON using smart-doc's ApiConfig Object. So the project configuration can also refer to the introduction of smart-doc.

Generated document

Run Plugin with MAVEN command

// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc: html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc: markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc: adoc
// Generate postman collection
mvn -Dfile.encoding=UTF-8 smart-doc: postman

// Apache Dubbo RPC
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc

Note: Under the window system, if you use the maven command line to perform document generation, non-English characters may be garbled, so you need to specify -Dfile.encoding = UTF-8 during execution.

View maven's coding

# mvn -version
Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T19:57:37+08:00)
Maven home: D:\ProgramFiles\maven\bin\..
Java version: 1.8.0_191, vendor: Oracle Corporation
Java home: D:\ProgramFiles\Java\jdk1.8.0_191\jre
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos"

Run Plugin in IDEA

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

smart-doc-maven-plugin

Use Gradle Plugin

If you use gradle to build the project, you can refer to the documentation of the gradle plugin to integrate, smart-doc-gradle-plugin

Generated document example

Interface header rendering

header

Request parameter example rendering

request-params

Response parameter example renderings

response-fields

Integration through unit tests

You can generate documentation by adding smart-doc dependencies directly to your project and then writing unit tests to start smart-doc. we still recommend that you use the smart-doc-maven-plugin plugin.

Use smart-doc by junit test

Building

You could build with the following commands. (Java 1.8 is required to build the master branch)

mvn clean install -Dmaven.test.skip=true

Contributors

Thanks to the following people who have submitted major pull requests:

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 is under the Apache 2.0 license. See the LICENSE file for details.

Contact

Email: 836575280@qq.com

Comments ( 0 )

Sign in for post a comment

About

smart-doc是一款同时支持java restful api和apache dubbo rpc接口文档生成的工具。完全基于注释生成文档,做到零侵入。 spread retract
Cancel

Releases

No release

Contributors

All

Activities

load more
can not load any more
Java
1
https://gitee.com/tkmeeta/smart-doc.git
git@gitee.com:tkmeeta/smart-doc.git
tkmeeta
smart-doc
smart-doc
master

Search