Shulou(Shulou.com)06/03 Report--

This article will explain in detail the example analysis of Swagger and YApi for you. The content of the article is of high quality, so the editor shares it for you as a reference. I hope you will have some understanding of the relevant knowledge after reading this article.

Recently, the front end has been reflecting that Swagger looks at the interface information is very uncomfortable, so I spent two hours to kill Swagger, using the legendary better use of YApi.

Swagger and YApi

In fact, I personally think that there is nothing wrong with Swagger, the back-end integration is convenient and fast, but UI is not good, and the code is too intrusive for Java.

Swagger interface

In addition to solving these problems, YApi also has rights management, teamwork, automated testing, support for OpenApi specifications, and so on.

YApi interface

The biggest difference between YApi and Swagger is that YApi needs to import documents (although it can also be imported through Swagger polling), while Swagger can discover them automatically.

I won't go into details about the installation here, but the official documentation is very clear. You can choose between command-line deployment, visual deployment, or Docker deployment.

Private network deployment is recommended. After all, most API documents are sensitive.

Document comment

YApi's document parsing is based on the Java annotation specification and there is no code intrusion! But this requires us to write document comments in accordance with the Javadoc specification, which is a prerequisite for using YApi. An interface document is divided into the following sections.

Interface class comments

Comments for the interface class, the following is the basic format. The first line will be displayed as a menu, as short as possible; the second line is a description of the interface, describing the role and details of the interface.

/ * * API category name *

* API remarks / description * * @ author felord * @ since v1.0 * / @ RestController @ RequestMapping ("/ foo") public class FooController {/ / omitted}

And @ module, @ copyright and so on, you don't have to write.

Parameter comment

The notes of input and output parameters have a wonderful effect with JSR-303.

/ * * basic account information * * @ author felord * @ since v1.0 * / @ Data public class UserInfoDetail {/ * * user name * * along with the JSR303 note states the constraint mode of this field [required] / @ NotBlank private String username; / * * Real name * / private String realName / * Mobile phone number * / private String phoneNumber; / * gender-1 unknown 0 female 1 male * * use @ see to indicate the source of the value of this field * @ see GenderType#value () * / private Integer gender; / * * nickname * / private String nickName / * Wechat * use {@ code Deprecated} to indicate that the dictionary will be discarded in the future * / @ Deprecated private String wechatAccount; / * * email * / private String email;}

Comments on interface methods

If the input parameter is a complex object, the annotation is referenced by @ link, and @ RequestBody specifies that Content-Type is application/json.

/ * * New user information * * @ param userInfoDetail user information parameter {@ link UserInfoDetail} * @ return {@ link Boolean} * / @ PostMapping ("/ bar") public boolean detail (@ RequestBody UserInfoDetail userInfoDetail) {return true;}

Style corresponding to Post request

If the parameter is a primitive type or String, you can write that @ RequestParam works wonders.

/ * get user information * * @ param name name * @ param age Age * @ return {@ link UserInfoDetail} * / @ GetMapping ("/ sam") public UserInfoDetail detailBySamples (@ RequestParam String name, Integer age) {return new UserInfoDetail ();}

Style corresponding to Get request

Import document

YApi supports Swagger, Postman, JSON and other ways to import documents. Personally, however, I prefer to use plug-in imports, and easy-yapi is recommended in Intellij IDEA. When importing, navigate to the corresponding Controller and use the shortcut key Alt+Ins to call out the shortcut menu.

Outbound shortcut menu

Select Export Yapi, and the first selection will let you enter the server address of YApi and the token string for the corresponding project.

Token string

After filling in in turn, the generated document is parsed and synchronized to the YApi server, and the result is what it looks like in the screenshot above. Then you can configure permissions to be assigned to team members, and repeat the above steps if there is a document update. YApi provides several strategies, you can choose to overwrite or not to overwrite.

This is the end of the sample analysis on Swagger and YApi. I hope the above content can be helpful to you and learn more knowledge. If you think the article is good, you can share it for more people to see.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.