This is the first day of my participation in Gwen Challenge

YDoc is a document generator that is less intrusive, concise and supports both native Swagger and YApi

A document generator that makes full use of SpringBoot’s own annotations to describe documents. Let’s ditch lots of annotations and configuration and embrace simplicity.

1.0.3 has some problems. Please use version 1.0.4, which has been released to Maven warehouse and is expected to be directly dependent on on 23rd. Currently, clone source code needs to be installed locally to use

Source code has been open source to Github welcome to contribute source code together, like a Star support

YDoc source Github repository address

The introduction

Whenever the project needs interface documentation, it will always use a restfulApi document generation tool like Swagger. I believe many people will be sick of its annotations and configuration when using it. If the project has no requirements for code specification, it can also be seen as a comment. In order to make it easier to use, I have written a dependency library based on Spring-boot-starter, which is based on YApi platform to manage API documents and permissions control, mock data, etc.

1. Compare other document generators

Here are two COMMON API document generators for the Java platform.

1.JDoc

JDoc is a tool to generate API documents according to document annotations. You need to write according to the document specifications defined by JDoc to generate corresponding interface documents. It does not support mock data, permission management, etc., cannot manage API centrally, and is forced to rely on Javadoc specification implementation.

• The advantage is that you only need to write Javadoc without introducing additional configuration.
• The disadvantages are enforced dependence on the Javadoc specification, unfriendly to API testing, and extra operations for generation.

2.Swagger2

Swagger is a tool for generating API documents in the form of annotations. The corresponding API documents can be generated only when the parameters and return values of the interface are annotated. It supports API testing but does not support mock data or permission management.

• The advantage is that the operation is simple, the interface generation is better, and the deployment is convenient with the program deployment.
• The disadvantages are cumbersome integration, heavy dependency on annotations, and increased development costs.

3.YDoc

Ydoc is a dependency library based on spring-boot-starter, lightweight, no Ui interface, does not rely on annotations, a small amount of annotations and usage specifications, overall rely on YApi interface visualization platform, can use all the characteristics of YApi, separated from the program deployment can be centralized management, support permission control, fast and efficient integration. Configuration dependencies, plus two lines that are automatically generated when the configuration program starts.

• The advantage is that it can use the features of the YApi platform, which is less intrusive. 0 configuration can be introduced to add a dependency configuration file.
• The disadvantage is that there is little reliance on annotations and usage specifications, and only spring-boot projects are supported

2. Use of YDoc (based on YApi version 1.9.2)

1. Need to build YApi document platform (YApi official document)
2. The ydoc-spring-boot-starter dependency is referenced in the project
3. Set ydoc.enable = true
4. If you want to use YApi, configure the URL of YApi and the token of the project in the configuration file
5. To use swagger-bootstrap-ui, add @enablesWagger2 to /doc.html
6. All want? All of the above can be configured.
7. Extra configuration? Sweep the package? If it does not exist, start it and use it

If not, you have not synchronized to central Maven (1.0.2 only supports Swagger-bootstrap-UI).

Release notes

1.0.1 Support YDoc to Generate YApi documents 1.0.2 Support YDoc to generate Swagger documents 1.0.3 Support Swagger native Annotations to generate Swagger documents and synchronize them to YApi But also want to quickly import YApi users, refuse to use YApi rotation import start from me)

       <dependency>
            <groupId>com.github.nobugboy</groupId>
            <artifactId>ydoc-spring-boot-starter</artifactId>
            <version>1.0.5</version>
        </dependency>
Copy the code

Note that when swagger-native is enabled, you need to delete the swagger dependency of the original project. (YDoc uses Swagger3.0 internally)

3. Steps of using YApi

1. Create the corresponding project on the established YApi platform
2. Click on the project, set the -token configuration, copy the token and paste it into the corresponding configuration of the Java project
3. Just start the app
4. Go back to the YApi project and the document has been generated

4. Parameter Description

Abandon a large number of Swagger annotations and configurations, and only need to add additional parameters to the annotations to describe the API or parameters during SpringBootWeb development, which greatly reduces the invasion of the project and simplifies the development process

@paramdesc and @paramignore are additional YDoc annotations, and the rest are SpringBoot annotations. @paramdesc identifies the description of parameters in the entity. @paramignore ignores parameters and does not participate in the document generation.

5. Enum type

Some optimization is made for the description of Enum type parameters that are troublesome in Swagger. If Enum type values are used, toString method needs to be rewritten in Enum to return a string as the description parameter. This method has higher freedom and can describe code and message well.

6. Use the YDoc specification recommendations

1. Whatever the request, if you use an object to receive the primitive type inside the object, is it recommended to use a wrapper class
2. You are advised to add @paramdesc to the parameter to describe the action
3. The annotations provided by Spring add a name to the existing development custom to describe the role of the RestController or Api
4. If a special parameter, such as Bindingresult, is specified, the login user entity is ignored using @paramIgnore

7. The voice

For details, please refer to the YDoc Tutorial