Simple use of swagger2

Simple use of swagger2

Advantages:
APIs in document form can be generated and provided to different teams.

Easy to test by yourself

This is very important because I have encountered such a situation at work that is caused by inconsistent development and use documents with the latest document versions, which makes it annoying in the future.

=== Use swagger process ===

1. Introduce pom dependency

<dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.4.0</version></dependency><dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger-ui</artifactId>    <version>2.4.0</version></dependency>

2. Create a swagger2 configuration class

New Class swagger2

@ Configuration // use the configuration class annotation @ enableswagger2 // enable this configuration class public class swagger2 {/*** @ Description: swagger2 configuration file, some basic content of swagger2 can be configured here, such as the scanned package. * // @ bean // configure this bean to enable swagger to scan the Controller public docket createrestapi () {// Add header parameters for swagger for input // parameterbuilder usertokenheader = new parameterbuilder (); // parameterbuilder useridheader = new parameterbuilder (); // list <parameter> pars = new arraylist <parameter> (); // usertokenheader. name ("headerusertoken "). description ("usertoken ")//. modelref (New modelref ("string ")). parametertype ("Header ")//. required (false ). build (); // useridheader. name ("headeruserid "). description ("userid ")//. modelref (New modelref ("string ")). parametertype ("Header ")//. required (false ). build (); // pars. add (usertokenheader. build (); // pars. add (useridheader. build (); return New docket (documentationtype. swagger_2 ). apiinfo ()). select (). APIS (requesthandlerselectors. basepackage ("com. csylh. controller ")). paths (pathselectors. any ()). build ();//. globaloperationparameters (PARs);}/*** @ Description: Information about building an API document */private apiinfo () {return New apiinfobuilder () // set the page title. title ("swagger2 build interface data document, here is the document title") // set contacts. contact (new contact ("song", "http://csylh.cn", "[email protected]") // description. description ("Left song short video, here is the description") // defines the version number. version ("V-1.0 "). build ();}}

3. Configure the Controller class, method, and object class

3.1 add an [email protected] to a controller

@ API: Used in the request class to describe the class
-Tags = "describes the role of this class. You can see the annotations on the UI interface"
-Value = "this parameter is meaningless and can be seen on the UI, so no configuration is required"
Case:
@ API (value = "user registration and logon interface", tags = {"login and logout controller "})
Public class usercontroller {}

3.2 define different controller interfaces (methods) [email protected]

@ Apioperation: Used in the request method to describe the purpose and function of the method.
-Value = "describes the purpose and function of the method"
-Notes = "method remarks"
Case:
@ Apioperation (value = "user registration interface", notes = "this is the user registration interface. You can write it at will ")
Public serverresponse register (@ requestbody users user ){
Return iuserservice. Register (User );
}

The following describes the classification of method parameters: (string userid, string fanid) parameter scenarios

Problem about method parameters: The above is a scenario like @ requestbody, sometimes it is a number of parameters (string userid, string fanid)
We can use @ apiimplicitparams to define parameters.
@ Apiimplicitparams: used in the request method to indicate a set of parameter descriptions.
-@ Apiimplicitparam: Used in the @ apiimplicitparams annotation to specify all aspects of a request parameter.
-Name: Parameter Name
-Value: Description and explanation of Chinese characters of the Parameter
-Required: Required Parameter
-Paramtype: where the parameter is stored
Header --> request parameter acquisition: @ requestheader
Query --> request parameter acquisition: @ requestparam
PATH (for restful Interface) --> request parameter acquisition: @ pathvariable
Body (not commonly used)
Form (not commonly used)
-Datatype: parameter type. The default value is string. Other values include datatype = "integer"
-Defaultvalue: Default Value of the Parameter
Case:
@ Apioperation (value = "user avatar upload", notes = "user avatar upload interface ")
@ Apiimplicitparam (name = "userid", value = "User ID", required = true,
Datatype = "string", paramtype = "query ")
Public serverresponse uploadicon (string userid, @ requestparam ("file") multipartfile [] files) throws ioexception {
Return iuserservice. uploadicon (userid, files );
}

Scenario 2: Use @ requestbody

After the above basic configuration, it can also be run, but we can better limit the passed users parameters. For example, the passed username parameter field cannot be empty.
Operation: configure the users object class.

Because users is an entity, it must be defined as @ apimodel.

@ Apimodel: Used in the response class to indicate the information of a response data.
This is generally used in scenarios such as @ requestbody when post is created.
When the request parameter cannot be described using the @ apiimplicitparam annotation)
Case:
@ Apimodel (value = "user object, here is the description", description = "this is a user object, here is the description ")
Public class users {}

Processing of fields in the object class

=== Fields that must be passed in from the front end [email protected]

// Username field @ apimodelproperty (value = "username", name = "username", example = "liuge36", required = true) Private string username; // The front-end password field @ apimodelproperty (value = "password", name = "password", example = "123456", required = true) Private string password;

=== Fields that do not need to be passed in at the front end, and do not need to be displayed @ apimodelproperty (hidden = true)
@ Apimodelproperty (hidden = true)
Private string ID;
In this way, it will not be displayed.

===Here, the basic usage is in place, and more swagger2 usage will be available in the future
Supplement: Define package Scanning
@ Mapperscan (basepackages = "com. csylh. mapper ")

Simple use of swagger2