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

In this issue, the editor will bring you what is the correct way to play Swagger2. The article is rich in content and analyzes and narrates it from a professional point of view. I hope you can get something after reading this article.

Introduction to Swagger2

To put it simply, the birth of Swagger2 is to solve the pain point that it is difficult to maintain API documents when developers communicate with each other. It can be perfectly combined with our Java program and can be used with another development tool, Spring Boot.

Start using the first step: import the POM file io.springfox springfox-swagger2 2.9.2 com.github.xiaoymin swagger-bootstrap-ui 1.9.0

# step 2: add a configuration class

We need to add a new configuration class for Swagger2Config:

/ * Swagger2 configuration class * @ author vi * @ since 2019-3-6 8:31 PM * / @ Configurationpublic class Swagger2Config {@ Bean public Docket createRestApi () {return new Docket (DocumentationType.SWAGGER_2) .a piInfo (apiInfo ()) .select () .apis (RequestHandlerSelectors.basePackage ("indi.viyoung.viboot.*")) Build (PathSelectors.any ()) .build () } private ApiInfo apiInfo () {return new ApiInfoBuilder () .title ("viboot-swagger2") / / title .description ("Restful-API-Doc") / / description .termsOfServiceUrl ("https://www.cnblogs.com/viyoung") / / the service website is configured here I wrote my blog park site ~ Welcome to follow ~ .contact (new Contact ("Vi's technical blog", "https://www.cnblogs.com/viyoung"," 18530069930@163.com ")) / / the three parameters are name, personal website, email. Version (" 1.0") / / version. Build () Step 3: add the configuration to the startup class

Be sure to add @ EnableSwagger2 annotations

/ * @ author vi * @ since 6:35 on 2019-3-6 PM * / @ SpringBootApplication@ComponentScan (value = "indi.viyoung.viboot.*") @ MapperScan (value = "indi.viyoung.viboot.swagger2.mapper") @ EnableSwagger2@EnableSwaggerBootstrapUIpublic class ViBootSwaggerApplication {public static void main (String [] args) {SpringApplication.run (ViBootSwaggerApplication.class, args);} step 4: complete the API document by annotating

1. @ Api

Annotation name annotation attribute scope attribute action @ Apitages class describes the role of this class

The value class describes the purpose of this class

For example:

@ Api (value = "user class controller", tags= "user class controller") public class UserController {.}

2. @ ApiOperation

Annotation name annotation attribute scope attribute action @ ApiOperation () value method description method action

Notes method prompt content

Tags method grouping

For example:

@ ApiOperation (value = "get user list", notes = "get user list") public List get () {.}

3. @ ApiParam

Annotation name annotation attribute scope attribute action @ ApiParam () name method parameter name

Parameter description of value method

Whether the required method parameter is required

For example:

@ ApiOperation (value= "get user details", notes= "get user details according to url's id") public User get (@ ApiParam (name= "id", value= "user id", required=true) Long id) {log.info ("GET.. {}... method execution." , id); return userService.getById (id);}

4. @ ApiModel & & @ ApiModelProperty

Annotation name Annotation attribute scope attribute function @ ApiModel () value class object name

Description class description @ ApiModelProperty () value method field description

Name method property name

DataType method property type

Whether the required method is required

An example of example method

Hidden by hidden method

For example:

@ ApiModel (value= "user object", description= "user object user") public class User implements Serializable {private static final long serialVersionUID = 1L; @ TableId (value= "id", type = IdType.AUTO) @ ApiModelProperty (value= "user ID", example = "1000001", hidden=true) private Long id; @ ApiModelProperty (value= "user name", required = true,dataType = "String") private String userName; @ ApiModelProperty (value= "password") private String password;}

5. @ ApiImplicitParam & & @ ApiImplicitParams

`@ ApiImpliciParam` can be used alone for method supremacy. If you have multiple parameters, you can put` @ ApiImpledParam` in `@ ApiImpledParams`. Only the attributes of` @ ApiImplinary Param` are listed here: annotated name annotated attribute scope attribute function @ ApiImplicitParam () value method parameter description

Name method parameter name

DataType method data type

ParamType method parameter type

An example of example method

For example:

@ ApiImplicitParams ({@ ApiImplicitParam (name = "user", value = "user entity user", required = true, dataType = "User")}) public void put (User user) {userService.updateById (user); log.info ("PUT method executes.") ;}

It is important to note that we did not write the two parameters in the circle in the annotation. This is to read the comment we just made for the User class and set the user name to be required!

6.@ApiResposne & & @ ApiResponses

The relationship between @ ApiResponses and @ ApiResponse is similar to that of @ ApiImplicitParam & & @ ApiImplicitParams.

Annotation name Annotation attribute scope attribute function @ ApiResponse () response method returns the class

Code method return code

The message method returns information

Example of examples method

Finally, let's talk about this UI.

First post a few ui of spring-fox (the one we are familiar with)

I believe that seeing here, everyone should have an answer to the choice of these two sets of UI. Of course, bootstrap-style ui is not only good-looking, but also has a variety of powerful functions.

Export md document

Parameter caching

The above is the correct way to play Swagger2 shared by the editor. If you happen to have similar doubts, you might as well refer to the above analysis to understand. If you want to know more about it, you are welcome to follow the industry information channel.

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.