Simple use of swagger2

Source: Internet
Author: User
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

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.