小城镇建设网站答案,wordpress安装后只有英文版,网站概念设计,重庆宣网站建设目录
一、Swagger简介
1.1 Swagger是什么#xff1f;
1.2 为什么要用Swagger
1.3 Swagger注解
二、Spring集成Swagger
三、测试环境配置 一、Swagger简介
1.1 Swagger是什么#xff1f; Swagger是一款RESTFUL接口的文档在线自动生成功能测试功能软件。Swagger是一个规…目录
一、Swagger简介
1.1 Swagger是什么
1.2 为什么要用Swagger
1.3 Swagger注解
二、Spring集成Swagger
三、测试环境配置 一、Swagger简介
1.1 Swagger是什么 Swagger是一款RESTFUL接口的文档在线自动生成功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。 1.2 为什么要用Swagger
1.2.1:对于后端开发人员来说
不用再手写WiKi接口拼大量的参数避免手写错误对代码侵入性低采用全注解的方式开发简单方法参数名修改、增加、减少参数都可以直接生效不用手动维护缺点增加了开发成本写接口还得再写一套参数配置 1.2.2:对于前端开发来说
后端只需要定义好接口会自动生成文档接口功能、参数一目了然联调方便如果出问题直接测试接口实时检查参数和返回值,就可以快速定位是前端还是后端的问题 1.2.3对于测试
对于某些没有前端界面UI的功能可以用它来测试接口操作简单不用了解具体代码就可以操作操作简单不用了解具体代码就可以操作 1.3 Swagger注解
Api注解 用在类上说明该类的作用。可以标记一个Controller类做为swagger文档资源。
属性说明valueurl的路径值tags如果设置这个值、value的值会被覆盖produces返回的格式类型例如application/json, application/xmlconsumes接收请求参数的类型例如application/json, application/xmlprotocolsPossible values: http, https, ws, wss.authorizations高级特性认证时配置 ApiOperation注解 用在方法上说明方法的作用每一个url资源的定义。
属性说明valueurl的路径值tags如果设置这个值、value的值会被覆盖produces返回的格式类型例如application/json, application/xmlconsumes接收请求参数的类型例如application/json, application/xmlhidden是否在文档中显示notes注释说明response返回的对象responseContainer这些对象是有效的 List, Set or Map.其他无效responseReference指定对响应类型的引用。指定的引用可以是本地的也可以是远程的*将按原样使用并覆盖任何指定的response()类responseHeaders响应旁边提供的可能标题列表httpMethodGET, HEAD, POST, PUT, DELETE, OPTIONS and PATCHcodehttp的状态码 默认 200 ApilmplicitParam 注解用来描述一个参数可以配置参数的中文含义也可以给参数设置默认值这样在接口测试的时候可以避免手动输入
属性说明paramType参数放在哪个地方name参数名称value参数代表的含义dataType参数类型dataTypeClass参数类型required是否必要defaultValue参数的默认值 paramType参数 类型作用path以地址的形式提交数据用于restful接口。请求参数采用PathVariable获取query直接跟参数完成自动映射赋值。请求参数可采用RequestParam获取body以流的形式提交仅支持POST。请求参数采用RequestBody获取header参数在request headers里边提交。请求参数采用RequestHeader获取form以form表单的形式提交仅支持POST。 ApiModel注解描述一个Model的信息这种一般用在post创建的时候使用RequestBody这样的场景请求参数无法使用 ApiImplicitParam注解进行描述的时候
ApiModelProperty注解描述一个model的属性。
属性说明value字段说明name参数名称dataType参数类型hidden在文档中隐藏required是否必要example举例说明notes注释说明 ApiParam注解 作用在方法的参数上用来描述接口的参数信息(一个参设置一个) ApiParam必须与RequestParam、PathVariable和RequestHeader一起使用。 属性说明name参数名称value参数简单描述defaultValue描述参数默认值required是否为必传参数, false:非必传; true:必传allowMultiple指定参数是否可以通过多次出现来接收多个值hidden隐藏参数列表中的参数example非请求体(body)类型的单个参数示例examplesExample(value ExampleProperty(mediaType “”, value “”)) 参数示例仅适用于请求体类型的请求 二、Spring集成Swagger
1、导入依赖 !--swager2--dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version/dependency!--swagger2模版样式--dependencygroupIdcom.github.xiaoymin/groupIdartifactIdswagger-bootstrap-ui/artifactIdversion1.9.6/version/dependency 新版3.0的直接加入启动器 dependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version/dependency3.0版本后不需要在加入enableopenapi和enableswagger2这两个注解 2、创建Swagger2配置类
package com.ycxw.boot.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;Configuration
EnableSwagger2
Profile({dev, test}) //dev(开发)、test(测试)、prod(生产)
public class Swagger2Configuration extends WebMvcConfigurationSupport {/*** 创建该API的基本信息 http://项目实际地址/doc.html*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title(SpringBoot集成Swagger2).description(测试系统).termsOfServiceUrl(ycxw320.blog.csdn.net).version(1.0.0).build();}/*** 创建API应用* apis接口包扫描路径* apiInfo() 增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现* 本例采用指定扫描的包路径来定义指定要建立API的目录。*/Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage(com.ycxw.boot.controller)).paths(PathSelectors.any()).build();}Overrideprotected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler(doc.html).addResourceLocations(classpath:/META-INF/resources/);registry.addResourceHandler(/webjars/**).addResourceLocations(classpath:/META-INF/resources/webjars/);}} 3、接着通过mybatis生成代码...
4、Swagger类与属性注释
package com.ycxw.boot.entity;import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;import java.io.Serializable;/*** p* 书本信息表* /p** author 云村小威* since 2023-12-20*/
Data
Accessors(chain true)
TableName(t_book)
ApiModel(书籍对象)
public class Book implements Serializable {private static final long serialVersionUID 1L;/*** 书本编号*/TableId(id)ApiModelProperty(书籍编号)private String id;/*** 书本名称*/TableField(bookname)ApiModelProperty(书籍名称)private String bookname;/*** 书本价格*/TableField(price)ApiModelProperty(书籍价格)private Float price;/*** 书本类型*/TableField(booktype)ApiModelProperty(书籍类型)private String booktype;/*逻辑删除隐藏*/TableField(status)ApiModelProperty(hidden true)private Integer status;/*乐观锁隐藏*/TableField(version)ApiModelProperty(hidden true)private Integer version;}5、Controller与接口方法注释
package com.ycxw.boot.controller;import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.core.toolkit.StringUtils;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.ycxw.boot.entity.Book;
import com.ycxw.boot.service.IBookService;
import com.ycxw.boot.tools.JsonResponseBody;
import com.ycxw.boot.tools.JsonResponseStatus;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.List;
import java.util.Objects;/*** p* 书本信息表 前端控制器* /p** author 云村小威* since 2023-12-20*/
RestController
RequestMapping(/book)
Api(value 书籍管理)
public class BookController {Autowiredprivate IBookService bookService;GetMapping(/list)ApiOperation(value 书籍查询所有)public JsonResponseBodyListBook list() {ListBook list bookService.list();if (!list.isEmpty()) {return JsonResponseBody.other(JsonResponseStatus.OK);} else {return JsonResponseBody.other(JsonResponseStatus.RESULT_EMPTY);}}PostMapping(/save)ApiOperation(value 新增书籍)public JsonResponseBodyBoolean save(Book book) {boolean save bookService.save(book);return JsonResponseBody.success(save);}GetMapping(/likeName)ApiOperation(value 获取商品集合,模糊查询)public JsonResponseBodyListBook list(Book goods) {QueryWrapperBook wrapper new QueryWrapper();wrapper.like(StringUtils.isNotEmpty(goods.getBookname()), bookname, goods.getBookname());ListBook list bookService.list(wrapper);return JsonResponseBody.success(list);}GetMapping(/show)ApiOperation(value 获取商品集合,模糊查询大于查询)ApiImplicitParams({ApiImplicitParam(name price, paramType query, value 价格, required true),ApiImplicitParam(name bookname, paramType query, value 名称, required true)})public JsonResponseBodyListBook listByNameAndPrice(Double price, String bookname) {QueryWrapperBook wrapper new QueryWrapper();wrapper.like(StringUtils.isNotEmpty(bookname), bookname, bookname);wrapper.gt(Objects.nonNull(price), price, price);ListBook list bookService.list(wrapper);return JsonResponseBody.success(list);}GetMapping(/page)ApiOperation(value 获取商品集合,分页查询模糊查询)public JsonResponseBodyListBook listPage(ApiParam(name bookname, value 模糊查询关键字)RequestParam(bookname)String bookname) {QueryWrapperBook wrapper new QueryWrapper();wrapper.like(StringUtils.isNotEmpty(bookname), bookname, bookname);PageBook page new Page();PageBook res bookService.page(page, wrapper);return JsonResponseBody.success(res.getRecords(), res.getTotal());}}6、访问本地链接
启动项目访问http://localhost:8080/doc.html 通过Swagger视图可以看到该项目的一些信息还有每个controller层的接口方法点击接口可以查看该接口的一些信息包括请求方式、地址、响应参数以及结果... 三、测试环境配置
在swagger配置类中我添加了一个这样的注解
Profile({dev, test}) //dev(开发)、test(测试)、prod(生产) 因为需要配置该测试文档只能在项目开发和测试阶段才能使用在yml配置中是这样配置的
spring:profiles:active: test
当然这样定死显然是不好的所以去掉这个配置将项目直接打成jar包通过指令设置测试环境运行。 1、设置开发环境中打开swagger测试文档 2、设置生成环境打开文档 可以看到在生成环境中不可查看接口文档 处于安全考虑我们在发布的时候需要关闭Swagger或者利用security授权登录才可查看接口文档 作为开发者养成良好的文档规范习惯是非常重要的无论使用Swagger还是其他文档工具编写清晰、详尽的API文档都应该是我们的素养之一。
