spring boot:用swagger3生成接口文档，支持全局通用参数(swagger 3.0.0 / spring boot 2.3.2) |
您所在的位置：网站首页 › a1822详情参数 › spring boot:用swagger3生成接口文档，支持全局通用参数(swagger 3.0.0 / spring boot 2.3.2) |
spring boot:用swagger3生成接口文档，支持全局通用参数(swagger 3.0.0 / spring boot 2.3.2)
|
一，什么是swagger? 1, Swagger 是一个规范和完整的文档框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务文档 官方网站: https://swagger.io/ 2，使用swagger要注意的地方: 在生产环境中必须关闭swagger, 它本身只用于前后端工程师之间的沟通, 可以专门使用一台内部服务器来展示ui供访问, 即使在这上面要做好安全措施3, 因为swagger3.0.0已发布，本文使用了最新版 如果有还在用2.x版本的请参考时注意区分 对应的源码可以访问这里获取： https://github.com/liuhongdi/ 二，演示项目的相关信息 1,项目地址 https://github.com/liuhongdi/swagger3 2,项目功能说明 演示了使用swagger3.0.0生成接口站的文档， 包括： 通用的全局参数, 响应时各种状态的返回 响应的封装后的result格式数据 3,项目结构:如图: 三，配置文件说明 1,pom.xml io.springfox springfox-boot-starter 3.0.0说明：用springfox-boot-starter来引入swagger 2,application.properties springfox.documentation.swagger-ui.enabled=true说明：在生产环境中要设置swagger-ui的enabled值为false,用来关闭文档的显示 四，java文件说明: 1,Swagger3Config.java @EnableOpenApi @Configuration public class Swagger3Config implements WebMvcConfigurer { @Bean public Docket createRestApi() { //返回文档摘要信息 return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) .paths(PathSelectors.any()) .build() .globalRequestParameters(getGlobalRequestParameters()) .globalResponses(HttpMethod.GET, getGlobalResonseMessage()) .globalResponses(HttpMethod.POST, getGlobalResonseMessage()); } //生成接口信息，包括标题、联系人等 private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger3接口文档") .description("如有疑问，请联系开发工程师老刘。") .contact(new Contact("刘宏缔", "https://www.cnblogs.com/architectforest/", "[email protected]")) .version("1.0") .build(); } //生成全局通用参数 private List getGlobalRequestParameters() { List parameters = new ArrayList(); parameters.add(new RequestParameterBuilder() .name("appid") .description("平台id") .required(true) .in(ParameterType.QUERY) .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))) .required(false) .build()); parameters.add(new RequestParameterBuilder() .name("udid") .description("设备的唯一id") .required(true) .in(ParameterType.QUERY) .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))) .required(false) .build()); parameters.add(new RequestParameterBuilder() .name("version") .description("客户端的版本号") .required(true) .in(ParameterType.QUERY) .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))) .required(false) .build()); return parameters; } //生成通用响应信息 private List getGlobalResonseMessage() { List responseList = new ArrayList(); responseList.add(new ResponseBuilder().code("404").description("找不到资源").build()); return responseList; } }说明：生成了全局的参数和通用的响应信息 2,RestResult.java @ApiModel("api通用返回数据") public class RestResult { //uuid,用作唯一标识符，供序列化和反序列化时检测是否一致 private static final long serialVersionUID = 7498483649536881777L; //标识代码，0表示成功，非0表示出错 @ApiModelProperty("标识代码,0表示成功，非0表示出错") private Integer code; //提示信息，通常供报错时使用 @ApiModelProperty("提示信息,供报错时使用") private String msg; //正常返回时返回的数据 @ApiModelProperty("返回的数据") private T data; //constructor public RestResult() { } //constructor public RestResult(Integer status, String msg, T data) { this.code = status; this.msg = msg; this.data = data; } //返回成功数据 public RestResult success(T data) { return new RestResult(ResponseCode.SUCCESS.getCode(), ResponseCode.SUCCESS.getMsg(), data); } public static RestResult success(Integer code,String msg) { return new RestResult(code, msg, null); } //返回出错数据 public static RestResult error(ResponseCode code) { return new RestResult(code.getCode(), code.getMsg(), null); } public Integer getCode() { return code; } public void setCode(Integer code) { this.code = code; } public String getMsg() { return msg; } public void setMsg(String msg) { this.msg = msg; } public T getData() { return data; } public void setData(T data) { this.data = data; }说明：这里要注意使用泛型T,如果只用Object,则swagger不能识别我们所返回的数据的类型说明: 其中:ApiModel用于类上面说明功能, ApiModelProperty用于字段上说明功能 尤其是getData方法的返回数据类型，要用T，使用工具生成的data类容易出现这种错误，3,Goods.java @ApiModel("商品模型") public class Goods { //商品id @ApiModelProperty("商品id") Long goodsId; public Long getGoodsId() { return this.goodsId; } public void setGoodsId(Long goodsId) { this.goodsId = goodsId; } //商品名称 @ApiModelProperty("商品名称") private String goodsName; public String getGoodsName() { return this.goodsName; } public void setGoodsName(String goodsName) { this.goodsName = goodsName; } //商品标题 @ApiModelProperty("商品标题") private String subject; public String getSubject() { return this.subject; } public void setSubject(String subject) { this.subject = subject; } //商品价格 @ApiModelProperty("商品价格") private BigDecimal price; public BigDecimal getPrice() { return this.price; } public void setPrice(BigDecimal price) { this.price = price; } //库存 @ApiModelProperty("商品库存") int stock; public int getStock() { return this.stock; } public void setStock(int stock) { this.stock = stock; } public String toString(){ return " Goods:goodsId=" + goodsId +" goodsName=" + goodsName+" subject=" + subject+" price=" + price+" stock=" + stock; } }4,GoodsController.java @Api(tags = "商品信息管理接口") @RestController @RequestMapping("/goods") public class GoodsController { @Operation(summary = "商品详情,针对得到单个商品的信息") @GetMapping("/one") public RestResult one(@Parameter(description = "商品id,正整数") @RequestParam(value="goodsid",required = false,defaultValue = "0") Integer goodsid) { Goods goodsone = new Goods(); goodsone.setGoodsId(3L); goodsone.setGoodsName("电子书"); goodsone.setSubject("学python,学ai"); goodsone.setPrice(new BigDecimal(60)); goodsone.setStock(10); RestResult res = new RestResult(); return res.success(goodsone); } @Operation(summary = "提交订单") @PostMapping("/order") @ApiImplicitParams({ @ApiImplicitParam(name="userid",value="用户id",dataTypeClass = Long.class, paramType = "query",example="12345"), @ApiImplicitParam(name="goodsid",value="商品id",dataTypeClass = Integer.class, paramType = "query",example="12345"), @ApiImplicitParam(name="mobile",value="手机号",dataTypeClass = String.class, paramType = "query",example="13866668888"), @ApiImplicitParam(name="comment",value="发货备注",dataTypeClass = String.class, paramType = "query",example="请在情人节当天送到") }) public RestResult order(@ApiIgnore @RequestParam Map params) { System.out.println(params); RestResult res = new RestResult(); return res.success("success"); } }说明：Api用来指定一个controller中的各个接口的通用说明 Operation:用来说明一个方法 @ApiImplicitParams:用来包含多个包含多个 @ApiImplicitParam， @ApiImplicitParam:用来说明一个请求参数 如果使用@Parameter来做说明，可以直接加到@RequestParam参数之前 @ApiIgnore:用来忽略不必要显示的参数五，效果测试 1,访问文档：访问: http://127.0.0.1:8080/swagger-ui/index.html 可以看到已有的接口: 2,查看接口的详情： 参数:可以看到我们添加的全局通用参数 六，查看spring boot的版本 . ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.3.2.RELEASE) |
响应: 
【本文地址】
今日新闻 |
推荐新闻 |