First of all, generally, the java server has used postman, written the api document interface of the front-end call, and also used some tools on the market.
The API automatically generates documents, which can save the time of writing documents.
Of course, there will be many similar open source tools at present. Let's compare several.
Comparison of api document writing
Why write these, because it involves the evolution of API documents
1. Traditional word documents
Internal use, using word fixed format, writing trouble, sharing more trouble
2,showdoc
The unified format of api documents is added, which makes it easier to write and share
3,swagger
java code comments are added and API documents are automatically generated. Basically, there is no need to write and sharing is more convenient. However, swagger has a big problem and is too intrusive
4,smartdoc+torna
Now more mainstream use
Standard notes + support for multi platform + test function
smartdoc
Official website:
introduce
Smart doc is the official organization of open source API document generation tools. The official is committed to providing java web developers with an API document generation tool. The current official open source products are smart doc, smart doc Maven plugin and smart doc gradle plugin.
Smart doc is a tool that supports both JAVA REST API and Apache Dubbo RPC interface document generation. Smart doc is the first in the industry to put forward the concept of derivation based on JAVA generic definition, analyze and generate interface documents completely based on interface source code, and do not use any annotations to invade business code. You only need to write comments according to the JAVA doc standard, and smart doc can help you generate a simple and clear Markdown, HTML5 and postman Collection2 0 +, OpenAPI 3.0 +.
function
Zero annotation, zero learning cost, only need to write standard JAVA annotations.
Automatic derivation based on source code interface definition and powerful derivation of return structure.
Support Spring MVC, Spring Boot, Spring Boot Web Flux(controller writing mode), Feign.
Support the derivation of Callable, Future, completable Future and other asynchronous interface returns.
Support JSR303 parameter verification specification on JavaBean, including grouping verification.
The interface for JSON request parameters can automatically generate simulated JSON parameters.
Some common field definitions can generate valid analog values.
Supports generating JSON return value examples.
It supports loading source code from outside the project to generate field comments (including jar packages published by standard specifications).
It supports the generation of documents in multiple formats: Markdown, HTML5, Asciidoctor, Postman Collection and OpenAPI 3.0. Up - open document data, free access to document management system.
It supports exporting error codes and various dictionary codes defined in the code to interface documents.
It supports Maven and Gradle plug-in easy integration.
Support Apache Dubbo RPC interface document generation.
debug interface debugging html5 page fully supports file upload and download (@ download tag tag tag download method) testing.
Maven Plugin
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>[Latest version]</version>
<configuration>
<!--Specifies the profile used by the to generate the document,Put the configuration file in your own project-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--Specify project name-->
<projectName>test</projectName>
<!--smart-doc Automatically analyze the dependency tree and load the source code of third-party dependencies. If some framework dependency libraries cannot be loaded, resulting in an error, please use excludes Exclude-->
<excludes>
<!--The format is: groupId:artifactId;Reference is as follows-->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
<!--From 1.0.8 From version, the plug-in provides includes support,Configured includes The plug-in will be loaded according to the user configuration instead of automatically, so you should pay attention to it when using it-->
<!--smart-doc It can automatically analyze the dependency tree and load all dependent source codes, which will affect the document construction efficiency in principle, so you can use it includes To let the plug-in load your configured components-->
<includes>
<!--The format is: groupId:artifactId;Reference is as follows-->
<!--Regular expressions can also be supported, such as: com.alibaba:.* -->
<include>com.alibaba:fastjson</include>
</includes>
</configuration>
<executions>
<execution>
<!--If you do not need to start at compile time smart-doc，Will phase Comment out-->
<phase>compile</phase>
<goals>
<!--smart-doc Provided html,openapi,markdown etc. goal，Configurable on demand-->
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
Personal configuration
<build>
<plugins>
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.2.3</version>
<configuration>
<configFile>./src/main/resources/smart-doc.json</configFile>
</configuration>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
smart-doc.json
The official configuration description is shown in: https://gitee.com/smart-doc-team/smart-doc
My test configuration:
{
"serverUrl": "http://127.0.0.1",
"isStrict": false,
"allInOne": true,
"packageFilters": "com.xy.saas.consumer.controller.*",
"projectName": "Test items",
"appKey": "20210811875071685840076800",
"appToken": "7b65406490ea48babedf52f73eddaa19",
"secret": "f#T0Qotd#<$O%hcsAmAn5uBAx!ZH.>^.",
"openUrl": "http://localhost:7700/api",
"debugEnvName":"testing environment",
"debugEnvUrl":"http://127.0.0.1",
"outPath":"doc"
}
Because I integrate torna, please refer to the official instructions for the specific configuration
be careful ⚠️:
1. The package name configured by packageFilters must be followed by '. *'
2. outPath must be configured
maven startdoc execution
//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 json data mvn -Dfile.encoding=UTF-8 smart-doc:postman // Generate open API 3.0 +, since smart doc Maven plugin 1.1 five mvn -Dfile.encoding=UTF-8 smart-doc:openapi // Generate documents and push them to the Torna platform mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest // Apache Dubbo RPC documentation // 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 // Generate dubbo interface documents and push them to torna mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc
be careful:
During generation, errors may be reported, or the package cannot be found. Try twice more.
torna
Go to the official website first. Generally, it's enough to read the official website, http://torna.cn
What can you do?
A picture on the official website makes it clear
Recommended combination
Smart doc + Torna to realize the automation of the whole document process
If you use the Java language, smart doc + Torna is recommended
Smart doc (opens new window) + Torna forms an industry-leading document generation and management solution. It uses smart doc to extract Java source code and comments without invasion, generate API documents, and automatically push the documents to the Torna enterprise interface document management platform.
Through this combination, you can realize that you can push the interface information to the Torna platform only after writing Java comments, so as to realize interface preview and interface debugging.
The pushed content includes: interface name / author/Path parameter / Header / request parameter / return parameter / dictionary list / public error code
If you are a non Java language, you can use the form page to edit the above contents. After completion, you can also preview and debug the interface.
Environmental preparation
Java 8, Torna requires java version at least Java 8
Maven 3, package management and build tool, minimum version requirement Maven 3
nodejs12. nodejs needs to be installed for front-end development. Version 12 is recommended. If the version is too high, there may be problems
Mysql5. 7 (recommended)
Project preparation
Download release: https://gitee.com/durcframework/torna/tags
mysql initialization, see the document
deploy
After development, the project needs to be packaged and released. The steps are as follows:
If your development environment is macOS/Linux, execute sh build SH, if it is a Windows system, double-click to execute build bat
The construction results are in dist/torna directory, and the final structure is as follows:
torna-<version> # root directory ├── application.properties # configuration file ├── dist # Front end resources ├── debug.sh # Online debugging ├── shutdown.sh # End service script ├── startup.bat # Start service script (windows) ├── startup.sh # Startup service script (macOS/Linux) └── torna.jar # Service procedure hold torna-<version>Upload folder to server
Modify application The content of the properties configuration file is changed to online configuration
Execute startup SH, start the application (Windows executes startup.bat)
visit: http://ip:7700
Account number: see the data in mysql initialization( admin@torna.cn ), the password is in the configuration file by default: 123456
verification
smartdoc performs tarna push
Compile push
Push complete
Browser view - management mode
Browser view - browse mode
View in browser - interface call
The function is similar to the simple version of postman, which can be seen at a glance..
end
At present, there are some other good api documents generated automatically. This thing is not the best. You can only try it yourself