springboot项目配置swagger2示例详解

swagger简介

　　Swagger是⼀款RESTful接⼝的⽂档在线⾃动⽣成、功能测试功能框架。⼀个规范和完整的框架，⽤于⽣成、描述、调⽤和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

　　当我们在后台的接⼝修改了后，swagger可以实现⾃动的更新，⽽不需要⼈为的维护这个接⼝进⾏测试。

⼀、swagger2中常⽤的注解作⽤

注解

@Api

@ApiOperation@ApiParam

作⽤

修饰整个类，描述Controller的作⽤ ，表⽰标识这个类是swagger的资源描述⼀个类的⼀个⽅法，或者说⼀个接⼝，表⽰⼀个http请求的操作⽤于⽅法的参数，表⽰对参数的添加元数据

@ApiModelProperty⽤于⽅法，字段。表⽰对model属性的说明或者数据操作更改

⼆、springboot项⽬配置swagger2步骤

1、springboot项⽬的⽬录结构如下：

2、pom.xml⽂件引⼊如下配置

org.springframework.boot spring-boot-starter-web

io.springfox

springfox-swagger2 2.9.2

io.springfox

springfox-swagger-ui 2.9.2

3、application.yml配置⽂件配置如下

server:

port: 8001 #端⼝ servlet:

context-path: /springSecurity #配置项⽬名称

4、Swagger配置⽂件如下：

package com.xz.springsecuritydemo.config;

import com.google.common.base.Predicate;import io.swagger.annotations.ApiOperation;

import org.springframework.beans.factory.annotation.Value;import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;import org.springframework.http.ResponseEntity;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;import static com.google.common.base.Predicates.or;

import static springfox.documentation.builders.PathSelectors.regex;/**

* @description: Swagger配置⽂件 * @author: xz */

@Configuration

@EnableSwagger2//开启Swagger2public class SwaggerConfig {

//注⼊配置⽂件中的项⽬名称

@Value(\"${server.servlet.context-path}\") private String contextPath;

/**

* 构建 swagger2 api ⽂档的详细信息函数 * @return */

private ApiInfo initApiInfo() {

ApiInfo apiInfo = new ApiInfoBuilder()

.title(\"springSecurity测试项⽬ Platform API\")//⼤标题 .version( \"1.0.0\")//版本

.description(initContextInfo())//描述

.contact(new Contact(\"xz\作者信息 .license(\"The System Server, Version 1.0\")//⽹站链接显⽰⽂字 .licenseUrl(\"https://wwwxz.blog.csdn.net/\")//⽹站链接 .build(); return apiInfo; }

private String initContextInfo() {

StringBuffer sb = new StringBuffer();

sb.append(\"REST API 设计在细节上有很多⾃⼰独特的需要注意的技巧，并且对开发⼈员在构架设计能⼒上⽐传统 API 有着更⾼的要求。\") .append(\"
\")

.append(\"本⽂通过翔实的叙述和⼀系列的范例，从整体结构，到局部细节，分析和解读了为了提⾼易⽤性和⾼效性，REST API 设计应该注意哪些问题以及如何解决这些问题。\"); return sb.toString(); }

/**

* swagger2的配置⽂件，这⾥可以配置swagger2的⼀些基本的内容，⽐如扫描的包等等 * @return */

@Bean

public Docket restfulApi() {

System.out.println(\"http://localhost:8001\" + contextPath + \"/swagger-ui.html\"); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(initApiInfo())

.groupName(\"RestfulApi\")

//.genericModelSubstitutes(DeferredResult.class) .genericModelSubstitutes(ResponseEntity.class) .useDefaultResponseMessages(true) .forCodeGeneration(false)

.pathMapping(contextPath) // base，最终调⽤接⼝后会和paths拼接在⼀起 .select()

//加了ApiOperation注解的类，才⽣成接⼝⽂档

//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //暴露接⼝地址的包路径（即此包下的类，才⽣成接⼝⽂档）

.apis(RequestHandlerSelectors.basePackage(\"com.xz.springsecuritydemo.modules.sys.controller\")) .paths(doFilteringRules())//⾃定义的过滤规则 .build(); }

/**

* 设置过滤规则

* 这⾥的过滤规则⽀持正则匹配 * @return */

private Predicate doFilteringRules() { return or(

regex(\"/testUser.*\"), regex(\"/hello.*\") ); }}

5、⽤户实体类如下：

package com.xz.springsecuritydemo.modules.sys.entity;import io.swagger.annotations.ApiModelProperty;/**

* @description: ⽤户实体类 * @author: xz */

public class UserQueryCondition { private int id;

@ApiModelProperty(value = \"⽤户名称\") private String name; private int age; public int getId() { return id; }

public void setId(int id) { this.id = id; }

public String getName() { return name; }

public void setName(String name) { this.name = name; }

public int getAge() { return age; }

public void setAge(int age) { this.age = age; }}

6、控制层代码如下：

package com.xz.springsecuritydemo.modules.sys.controller;

import com.xz.springsecuritydemo.modules.sys.entity.User;

import com.xz.springsecuritydemo.modules.sys.entity.UserQueryCondition;import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;

import org.apache.commons.lang.builder.ReflectionToStringBuilder;

import org.apache.commons.lang.builder.ToStringStyle;import org.springframework.web.bind.annotation.*;/**

* @description: 控制层代码如下 * @author: xz */

@Api(value = \"API - UserController\⽤户模块接⼝详情\")@RestController

@RequestMapping(\"/testUser\")public class UserController {

/***

* @ApiParam 如果⽅法接受的是具体参数，此注解需要加到⽅法中的参数上 */

@RequestMapping(value = \"/queryUserByName\ @ApiOperation(value = \"根据⽤户名称查询服务\")

public void queryUserByName(@ApiParam(value = \"⽤户username\") @RequestParam(name=\"username\ System.out.println(\"queryUser=====\"+name); }

/***

* @ApiOperation 可⽤在⽅法头上.参数的描述容器

* @ApiModelProperty 如果⽅法接受的是实体，此注解需要加到实体的具体属性上 */

@RequestMapping(value = \"/queryUserAll\ @ApiOperation(value = \"根据⽤户id、名称和年龄查询服务\")

public void queryUserAll(UserQueryCondition userQueryCondition){ //利⽤反射⼯具把对象输出

System.out.println(ReflectionToStringBuilder.toString(userQueryCondition, ToStringStyle.MULTI_LINE_STYLE)); }

/***

* @ApiOperation 可⽤在⽅法头上.参数的描述容器 */

@PostMapping(value = \"/createUser\") @ApiOperation(value = \"⽤户新增服务\")

public User userCreate1(@RequestBody User user){

System.out.println(user.getName()+\"----\"+user.getPassword()); user.setId(1); return user; }

/***

* @ApiOperation 可⽤在⽅法头上.参数的描述容器 */

@PutMapping(\"/{id:\\\\d+}\")

@ApiOperation(value = \"⽤户修改服务\")

public User update(@RequestBody User user){

System.out.println(user.getId()+\"======\"+user.getName()+\"----\"+user.getPassword()); user.setId(1); return user; }

/***

* @ApiOperation 可⽤在⽅法头上.参数的描述容器 */

@DeleteMapping(\"/{id:\\\\d+}\")

@ApiOperation(value = \"⽤户删除服务\") public void delete(@PathVariable String id){ System.out.println(id); }}

7、启动项⽬，如下图：

9、点击user-Controller,如下图所⽰：

10、点击具体某⼀⽅法，可以看到如下信息：

三、⽰例中使⽤的注解解析

1、@Api注解标注在了控制层的UserController类上，如下图画红⾊框的位置可以看到注解⽣效。

2、@ApiOperation注解标注在了控制层的UserController类的⽅法上，如下图画红⾊框的位置可以看到注解⽣效。

3、@ApiParam注解标注在了控制层的⽅法参数上，如下图画红⾊框的位置可以看到注解⽣效。

4、@ApiModelProperty注解标注在了实体中的属性上，在控制层⽅法接收实体对象时⽣效，如下图画红⾊框的位置可以看到注解⽣效。

到此这篇关于springboot项⽬配置swagger2⽰例详解的⽂章就介绍到这了,更多相关springboot配置swagger2内容请搜索以前的⽂章或继续浏览下⾯的相关⽂章希望⼤家以后多多⽀持！