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

This article is to share with you about how to use swagger2 to build Restful APIs in SpringBoot. The editor thinks it is very practical, so I share it with you. I hope you can get something after reading this article.

The first step is to introduce the corresponding jar package:

Io.springfox springfox-swagger2 2.6.0 io.springfox springfox-swagger-ui 2.6.0

The second step, basic information configuration:

@ Configuration@EnableSwagger2public class Swagger2Config {/ * in this configuration class, we instantiate a Docket object, which mainly includes three aspects of information:-- the description information of the entire API, that is, the information included by the ApiInfo object, which will be displayed on the page. -- specifies the name of the package that generates the API document. -- specify the path to generate the API. Four modes can be supported to generate API by path You can refer to its source code: * * / @ Bean public Docket createRestApi () {return new Docket (DocumentationType.SWAGGER_2) .apiInfo (apiInfo ()) .select () .apis (RequestHandlerSelectors.basePackage ("com.zzw.bootlaunch.rest")) .build (PathSelectors.regex ("/ rest/.*")) .build () } private ApiInfo apiInfo () {return new ApiInfoBuilder () .title ("XXX system API") .description ("this is a description of a XXX system") .termsOfServiceUrl ("http://127.0.0.1:8080") .contact (" zhangsanfeng ") .version (" V1.0 ") ") .build () }}

The basic configuration is a description of the entire API document and some global configuration that works for all interfaces. Here are two notes:

@ Configuration means that this is a configuration class, a comment that comes with JDK, as explained in the previous article.

The purpose of @ EnableSwagger2 is to enable Swagger2-related features.

In this configuration class, we instantiate a Docket object, which mainly includes three aspects of information:

The description of the entire API, that is, the information included by the ApiInfo object, is displayed on the page.

Specifies the name of the package that generates the API document.

Specifies the path where the API is generated. Four modes are supported for generating API by path, which can be found in its source code:

Public class PathSelectors {private PathSelectors () {throw new UnsupportedOperationException ();} public static Predicate any () {return Predicates.alwaysTrue ();} public static Predicate none () {return Predicates.alwaysFalse ();} public static Predicate regex (final String pathRegex) {return new Predicate () {public boolean apply (String input) {return input.matches (pathRegex) };} public static Predicate ant (final String antPattern) {return new Predicate () {public boolean apply (String input) {AntPathMatcher matcher = new AntPathMatcher (); return matcher.match (antPattern, input);}};}}

As can be seen from the source code, Swagger supports four ways: any path is generated, no path is generated, and regular matching and ant pattern matching are supported. You may be more familiar with the first three, the last ant matching, if you are not familiar with ant, then just ignore it, the first three should be enough for everyone to use in daily work.

Write service classes in rest style

@ Slf4j@RestController@RequestMapping ("/ rest") public class ArticleRestController {@ Resource ArticleRestService articleRestService; / * Save * * / @ RequestMapping (value= "/ article", method = RequestMethod.POST, produces = "application/json") public AjaxResponse saveArticle (@ RequestBody Article article) {log.info ("saveArticle: {}", article); / / operate database articleRestService.saveArticle (article); return AjaxResponse.sucess (article) Delete * * / @ RequestMapping (value= "/ article/ {id}", method = RequestMethod.DELETE, produces = "application/json") public AjaxResponse delArticle (@ PathVariable Long id) {log.info ("delArticle: {}", id); / / operate database articleRestService.deleteArticle (id); return AjaxResponse.sucess (id) } / * Update * * / @ RequestMapping (value= "/ article/ {id}", method = RequestMethod.PUT, produces = "application/json") public AjaxResponse updateArtice (@ PathVariable Long id, @ RequestBody Article article) {log.info ("updateArtice: {}", article); / / operate database article.setId (id); articleRestService.updateArticle (article); return AjaxResponse.sucess (article) } / * get a single record * * / @ RequestMapping (value = "/ article/ {id}", method = RequestMethod.GET Produces = "application/json") public AjaxResponse getArtice (@ PathVariable Long id) {/ * Article article = Article.builder () .id (22L) .author ("Zhang San") .content ("I am the content....") .title ("I am the title...") .createTime (new Date ()) .build () Log.info ("getArtice: {}", article); * / / operate database Article article = articleRestService.getArticle (id); return AjaxResponse.sucess (article);}

Step 3, launch and access

Start Spring boot, and then visit: http://127.0.0.1:8080/swagger-ui.html to see the following results:

We can also click in to take a look at each specific interface. Here we take the "POST / rest/article" interface as an example:

As you can see, Swagger generates examples of return results and request parameters for each interface, and can be accessed directly through the "try it out" below, and the interface is tested. On the whole, it feels that Swagger is still very powerful and easy to configure.

III. Detailed configuration of Swagger API

But if you look at this, you must have some questions:

The first question: neither the return result nor the request parameter has a literal description in Chinese. Can this be configured?

The second question: this request parameter should be the result reflected directly from the object, but not every attribute of the object is required, and the value of the parameter may not necessarily meet our needs. Can this be configured?

The answer is definitely yes. Now let's solve these two problems and look directly at the configuration code:

List page:

As you can see, the APIs are now under the tag of Article, and there are instructions on the back of the APIs that we have configured. Let's take a look at the details page of the "POST / rest/article" interface:

If our request parameter is an object, how to configure it? This involves two other annotations: @ ApiModel and @ ApiModelProperty, so let's look at the code first and then explain it to make it easier to understand:

@ ApiModel (value= "article object", description= "add & update article object description") public class Article {@ Id @ GeneratedValue @ ApiModelProperty (name = "id", value= "article ID", required = false,example = "1") private Long id; @ ApiModelProperty (name = "title", value= "article title", required = true,example = "test article title") private String title @ ApiModelProperty (name = "summary", value = "article abstract", required = true,example = "test article summary") private String summary; @ ApiModelProperty (hidden = true) private Date createTime; @ ApiModelProperty (hidden = true) private Date publicTime; @ ApiModelProperty (hidden = true) private Date updateTime; @ ApiModelProperty (hidden = true) private Long userId @ ApiModelProperty (name = "status", value = "post status", required = true,example = "1") private Integer status; @ ApiModelProperty (name = "type", value = "article category", required = true,example = "1") private Integer type;}

@ ApiModel is the configuration of the properties of the entire class:

Value: description of the class

Description: detailed description

@ ApiModelProperty is the property configuration for each field:

Name: field name

Value: description of the field

Required: is it necessary

Example: sample valu

Hidden: whether to display or not

After completing the above configuration, we will see the effect:

After clicking Try it out, we can see the returned result:

Operation is still very convenient, compared with Junit and postman, through Swagger testing will be more convenient, of course, Swagger testing can not replace unit testing, but it still plays a very important role in joint debugging.

The above is how to use swagger2 to build Restful APIs in SpringBoot. The editor believes that there are some knowledge points that we may see or use in our daily work. I hope you can learn more from this article. For more details, please 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.