spring与swagger2进行融合生成在线文档与自测

2024-06-20 16:18

本文主要是介绍spring与swagger2进行融合生成在线文档与自测,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

开源代码中学习到的东西

(1)Maven

<swagger2.version>2.9.2</swagger2.version>
<swagger-models.version>1.6.0</swagger-models.version>
<swagger-annotations.version>1.6.0</swagger-annotations.version>
<!--Swagger-UI API文档生产工具-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger2.version}</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${swagger2.version}</version>
</dependency>
<!--解决Swagger 2.9.2版本NumberFormatException-->
<dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>${swagger-models.version}</version>
</dependency>
<dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>${swagger-annotations.version}</version>
</dependency>

(2)如何使用

package com.macro.mall.common.config;import com.macro.mall.common.domain.SwaggerProperties;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;
import java.util.List;/*** Swagger基础配置* Created by macro on 2020/7/16.*/
public abstract class BaseSwaggerConfig {@Beanpublic Docket createRestApi() {SwaggerProperties swaggerProperties = swaggerProperties();Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo(swaggerProperties)).select().apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage())).paths(PathSelectors.any()).build();if (swaggerProperties.isEnableSecurity()) {docket.securitySchemes(securitySchemes()).securityContexts(securityContexts());}return docket;}private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {return new ApiInfoBuilder().title(swaggerProperties.getTitle()).description(swaggerProperties.getDescription()).contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail())).version(swaggerProperties.getVersion()).build();}private List<ApiKey> securitySchemes() {//设置请求头信息List<ApiKey> result = new ArrayList<>();ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");result.add(apiKey);return result;}private List<SecurityContext> securityContexts() {//设置需要登录认证的路径List<SecurityContext> result = new ArrayList<>();result.add(getContextByPath("/*/.*"));return result;}private SecurityContext getContextByPath(String pathRegex) {return SecurityContext.builder().securityReferences(defaultAuth()).forPaths(PathSelectors.regex(pathRegex)).build();}private List<SecurityReference> defaultAuth() {List<SecurityReference> result = new ArrayList<>();AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;result.add(new SecurityReference("Authorization", authorizationScopes));return result;}/*** 自定义Swagger配置*/public abstract SwaggerProperties swaggerProperties();
}
package com.macro.mall.demo.config;import com.macro.mall.common.config.BaseSwaggerConfig;
import com.macro.mall.common.domain.SwaggerProperties;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** Swagger API文档相关配置* Created by macro on 2019/4/8.*/
@Configuration
@EnableSwagger2
public class SwaggerConfig extends BaseSwaggerConfig {@Overridepublic SwaggerProperties swaggerProperties() {return SwaggerProperties.builder().apiBasePackage("com.macro.mall.demo.controller").title("mall-demo系统").description("SpringBoot版本中的一些示例").contactName("macro").version("1.0").enableSecurity(true).build();}}

model

package com.macro.mall.common.domain;import lombok.Builder;
import lombok.Data;
import lombok.EqualsAndHashCode;/*** Swagger自定义配置* Created by macro on 2020/7/16.*/
@Data
@EqualsAndHashCode(callSuper = false)
@Builder
public class SwaggerProperties {/*** API文档生成基础路径*/private String apiBasePackage;/*** 是否要启用登录认证*/private boolean enableSecurity;/*** 文档标题*/private String title;/*** 文档描述*/private String description;/*** 文档版本*/private String version;/*** 文档联系人姓名*/private String contactName;/*** 文档联系人网址*/private String contactUrl;/*** 文档联系人邮箱*/private String contactEmail;
}
package com.macro.mall.demo.dto;import com.macro.mall.demo.validator.FlagValidator;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;/*** 品牌传递参数*/
@ApiModel(value = "PmsBrandDto")
public class PmsBrandDto {@ApiModelProperty(value = "品牌名称",required = true)@NotNull(message = "名称不能为空")private String name;@ApiModelProperty(value = "品牌首字母",required = true)@NotNull(message = "首字母不能为空")private String firstLetter;@ApiModelProperty(value = "排序字段")@Min(value = 0, message = "排序最小为0")private Integer sort;@ApiModelProperty(value = "是否为厂家制造商")@FlagValidator(value = {"0","1"}, message = "厂家状态不正确")private Integer factoryStatus;@ApiModelProperty(value = "是否进行显示")@FlagValidator(value = {"0","1"}, message = "显示状态不正确")private Integer showStatus;@ApiModelProperty(value = "品牌logo")private String logo;@ApiModelProperty(value = "品牌大图")private String bigPic;@ApiModelProperty(value = "品牌故事")private String brandStory;public String getName() {return name;}public void setName(String name) {this.name = name;}public String getFirstLetter() {return firstLetter;}public void setFirstLetter(String firstLetter) {this.firstLetter = firstLetter;}public Integer getSort() {return sort;}public void setSort(Integer sort) {this.sort = sort;}public Integer getFactoryStatus() {return factoryStatus;}public void setFactoryStatus(Integer factoryStatus) {this.factoryStatus = factoryStatus;}public Integer getShowStatus() {return showStatus;}public void setShowStatus(Integer showStatus) {this.showStatus = showStatus;}public String getLogo() {return logo;}public void setLogo(String logo) {this.logo = logo;}public String getBigPic() {return bigPic;}public void setBigPic(String bigPic) {this.bigPic = bigPic;}public String getBrandStory() {return brandStory;}public void setBrandStory(String brandStory) {this.brandStory = brandStory;}
}

应用:

package com.macro.mall.demo.controller;import com.macro.mall.common.api.CommonPage;
import com.macro.mall.common.api.CommonResult;
import com.macro.mall.demo.dto.PmsBrandDto;
import com.macro.mall.demo.service.DemoService;
import com.macro.mall.model.PmsBrand;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;import java.util.List;/*** 品牌管理示例controller*/
@Api(tags = "DemoController", description = "品牌管理示例接口")
@Controller
public class DemoController {@Autowiredprivate DemoService demoService;private static final Logger LOGGER = LoggerFactory.getLogger(DemoController.class);@ApiOperation(value = "获取全部品牌列表")@RequestMapping(value = "/brand/listAll", method = RequestMethod.GET)@ResponseBodypublic CommonResult<List<PmsBrand>> getBrandList() {return CommonResult.success(demoService.listAllBrand());}@ApiOperation(value = "添加品牌")@RequestMapping(value = "/brand/create", method = RequestMethod.POST)@ResponseBodypublic CommonResult createBrand(@Validated @RequestBody PmsBrandDto pmsBrand) {CommonResult commonResult;int count = demoService.createBrand(pmsBrand);if (count == 1) {commonResult = CommonResult.success(pmsBrand);LOGGER.debug("createBrand success:{}", pmsBrand);} else {commonResult = CommonResult.failed("操作失败");LOGGER.debug("createBrand failed:{}", pmsBrand);}return commonResult;}@ApiOperation(value = "更新品牌")@RequestMapping(value = "/brand/update/{id}", method = RequestMethod.POST)@ResponseBodypublic CommonResult updateBrand(@PathVariable("id") Long id, @Validated @RequestBody PmsBrandDto pmsBrandDto) {CommonResult commonResult;int count = demoService.updateBrand(id, pmsBrandDto);if (count == 1) {commonResult = CommonResult.success(pmsBrandDto);LOGGER.debug("updateBrand success:{}", pmsBrandDto);} else {commonResult = CommonResult.failed("操作失败");LOGGER.debug("updateBrand failed:{}", pmsBrandDto);}return commonResult;}@ApiOperation(value = "删除品牌")@RequestMapping(value = "/brand/delete/{id}", method = RequestMethod.GET)@ResponseBodypublic CommonResult deleteBrand(@PathVariable("id") Long id) {int count = demoService.deleteBrand(id);if (count == 1) {LOGGER.debug("deleteBrand success :id={}", id);return CommonResult.success(null);} else {LOGGER.debug("deleteBrand failed :id={}", id);return CommonResult.failed("操作失败");}}@ApiOperation(value = "分页获取品牌列表")@RequestMapping(value = "/brand/list", method = RequestMethod.GET)@ResponseBodypublic CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,@RequestParam(value = "pageSize", defaultValue = "3") Integer pageSize) {List<PmsBrand> brandList = demoService.listBrand(pageNum, pageSize);return CommonResult.success(CommonPage.restPage(brandList));}@ApiOperation(value = "根据编号查询品牌信息")@RequestMapping(value = "/brand/{id}", method = RequestMethod.GET)@ResponseBodypublic CommonResult<PmsBrand> brand(@PathVariable("id") Long id) {return CommonResult.success(demoService.getBrand(id));}
}

访问:

http://localhost:8082/swagger-ui.html

这篇关于spring与swagger2进行融合生成在线文档与自测的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/1078632

相关文章

Spring 请求之传递 JSON 数据的操作方法

《Spring请求之传递JSON数据的操作方法》JSON就是一种数据格式,有自己的格式和语法,使用文本表示一个对象或数组的信息,因此JSON本质是字符串,主要负责在不同的语言中数据传递和交换,这... 目录jsON 概念JSON 语法JSON 的语法JSON 的两种结构JSON 字符串和 Java 对象互转

JAVA保证HashMap线程安全的几种方式

《JAVA保证HashMap线程安全的几种方式》HashMap是线程不安全的,这意味着如果多个线程并发地访问和修改同一个HashMap实例,可能会导致数据不一致和其他线程安全问题,本文主要介绍了JAV... 目录1. 使用 Collections.synchronizedMap2. 使用 Concurren

Java Response返回值的最佳处理方案

《JavaResponse返回值的最佳处理方案》在开发Web应用程序时,我们经常需要通过HTTP请求从服务器获取响应数据,这些数据可以是JSON、XML、甚至是文件,本篇文章将详细解析Java中处理... 目录摘要概述核心问题:关键技术点:源码解析示例 1:使用HttpURLConnection获取Resp

Java的栈与队列实现代码解析

《Java的栈与队列实现代码解析》栈是常见的线性数据结构,栈的特点是以先进后出的形式,后进先出,先进后出,分为栈底和栈顶,栈应用于内存的分配,表达式求值,存储临时的数据和方法的调用等,本文给大家介绍J... 目录栈的概念(Stack)栈的实现代码队列(Queue)模拟实现队列(双链表实现)循环队列(循环数组

使用Python从PPT文档中提取图片和图片信息(如坐标、宽度和高度等)

《使用Python从PPT文档中提取图片和图片信息(如坐标、宽度和高度等)》PPT是一种高效的信息展示工具,广泛应用于教育、商务和设计等多个领域,PPT文档中常常包含丰富的图片内容,这些图片不仅提升了... 目录一、引言二、环境与工具三、python 提取PPT背景图片3.1 提取幻灯片背景图片3.2 提取

Android实现在线预览office文档的示例详解

《Android实现在线预览office文档的示例详解》在移动端展示在线Office文档(如Word、Excel、PPT)是一项常见需求,这篇文章为大家重点介绍了两种方案的实现方法,希望对大家有一定的... 目录一、项目概述二、相关技术知识三、实现思路3.1 方案一:WebView + Office Onl

Java中Switch Case多个条件处理方法举例

《Java中SwitchCase多个条件处理方法举例》Java中switch语句用于根据变量值执行不同代码块,适用于多个条件的处理,:本文主要介绍Java中SwitchCase多个条件处理的相... 目录前言基本语法处理多个条件示例1:合并相同代码的多个case示例2:通过字符串合并多个case进阶用法使用

Java中的Lambda表达式及其应用小结

《Java中的Lambda表达式及其应用小结》Java中的Lambda表达式是一项极具创新性的特性,它使得Java代码更加简洁和高效,尤其是在集合操作和并行处理方面,:本文主要介绍Java中的La... 目录前言1. 什么是Lambda表达式?2. Lambda表达式的基本语法例子1:最简单的Lambda表

Java中Scanner的用法示例小结

《Java中Scanner的用法示例小结》有时候我们在编写代码的时候可能会使用输入和输出,那Java也有自己的输入和输出,今天我们来探究一下,对JavaScanner用法相关知识感兴趣的朋友一起看看吧... 目录前言一 输出二 输入Scanner的使用多组输入三 综合练习:猜数字游戏猜数字前言有时候我们在

Spring Security+JWT如何实现前后端分离权限控制

《SpringSecurity+JWT如何实现前后端分离权限控制》本篇将手把手教你用SpringSecurity+JWT搭建一套完整的登录认证与权限控制体系,具有很好的参考价值,希望对大家... 目录Spring Security+JWT实现前后端分离权限控制实战一、为什么要用 JWT?二、JWT 基本结构