springboot项目配置swagger2示例详解 springboot项目配置swagger2示例详

swagger简介 Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。
当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。
一、swagger2中常用的注解作用

注解	作用
@Api	修饰整个类，描述Controller的作用，表示标识这个类是swagger的资源
@ApiOperation	描述一个类的一个方法，或者说一个接口，表示一个http请求的操作
@ApiParam	用于方法的参数，表示对参数的添加元数据
@ApiModelProperty	用于方法，字段。表示对model属性的说明或者数据操作更改

二、springboot项目配置swagger2步骤 1、springboot项目的目录结构如下：

文章图片

2、pom.xml文件引入如下配置

org.springframework.bootspring-boot-starter-webio.springfoxspringfox-swagger22.9.2io.springfoxspringfox-swagger-ui2.9.2

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

server:port: 8001 #端口servlet:context-path: /springSecurity #配置项目名称

【springboot项目配置swagger2示例详解】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", "https://wwwxz.blog.csdn.net/", "123456@qq.com"))//作者信息.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*/@Beanpublic 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 = "https://www.it610.com/article/用户名称")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 = "https://www.it610.com/article/API - UserController",description = "用户模块接口详情")@RestController@RequestMapping("/testUser")public class UserController {/****@ApiParam 如果方法接受的是具体参数，此注解需要加到方法中的参数上*/@RequestMapping(value = "https://www.it610.com/queryUserByName",method = RequestMethod.GET)@ApiOperation(value = "https://www.it610.com/article/根据用户名称查询服务")public void queryUserByName(@ApiParam(value = "https://www.it610.com/article/用户username") @RequestParam(name="username",required = false, defaultValue ="https://www.it610.com/article/tom" ) String name){System.out.println("queryUser====="+name); }/**** @ApiOperation 可用在方法头上.参数的描述容器* @ApiModelProperty 如果方法接受的是实体，此注解需要加到实体的具体属性上*/@RequestMapping(value = "https://www.it610.com/queryUserAll",method = RequestMethod.GET)@ApiOperation(value = "https://www.it610.com/article/根据用户id、名称和年龄查询服务")public void queryUserAll(UserQueryCondition userQueryCondition){//利用反射工具把对象输出System.out.println(ReflectionToStringBuilder.toString(userQueryCondition, ToStringStyle.MULTI_LINE_STYLE)); }/**** @ApiOperation 可用在方法头上.参数的描述容器*/@PostMapping(value = "https://www.it610.com/createUser")@ApiOperation(value = "https://www.it610.com/article/用户新增服务")public User userCreate1(@RequestBody User user){System.out.println(user.getName()+"----"+user.getPassword()); user.setId(1); return user; }/**** @ApiOperation 可用在方法头上.参数的描述容器*/@PutMapping("/{id:\\d+}")@ApiOperation(value = "https://www.it610.com/article/用户修改服务")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 = "https://www.it610.com/article/用户删除服务")public void delete(@PathVariable String id){System.out.println(id); }}

7、启动项目，如下图：