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

本文主要是介绍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