SpringBoot集成Swagger文档及自定义访问路径

Swagger文档框架

一、介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

二、SpringBoot使用默认集成

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version><exclusions><exclusion><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId></exclusion><exclusion><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId></exclusion></exclusions></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>1.5.21</version></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.5.21</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

SwaggerConfig.java

@Configuration@EnableSwagger2public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.bxc.conformity.Swagger.DemoController"))//.paths(PathSelectors.regex("/App/.*|Thirdparty/.*")).paths(PathSelectors.regex("(/App/.*)|(/Thirdparty/.*)")).build().securitySchemes(securitySchemes()).securityContexts(securityContexts());}private List<ApiKey> securitySchemes() {List<ApiKey> apiKeyList = new ArrayList();apiKeyList.add(new ApiKey("Token", "token", "header"));return apiKeyList;}private List<SecurityContext> securityContexts() {List<SecurityContext> securityContexts = new ArrayList<>();securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth()).forPaths(PathSelectors.regex("^(?!auth).*$")).build());return securityContexts;}List<SecurityReference> defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;List<SecurityReference> securityReferences = new ArrayList<>();securityReferences.add(new SecurityReference("Token", authorizationScopes));return securityReferences;}private ApiInfo apiInfo() {//访问地址 http://localhost:8085/swagger-ui.htmlreturn new ApiInfoBuilder().title("接口文档 1.0.0").description("哈哈网络科技有限公司").version("1.0.0").build();}}

使用

@Api(tags = "接口")@RestController@RequestMapping("/App")public class SwController {@ApiOperation(value = "添加用户",notes = " username 用户名 \n" +"passwd密码 \n" +"company 公司名称 \n" +"child_number 子用户个数 \n")@PostMapping("/AddUser")public ResponseTemplate AddUser(@RequestBody@ApiParam(value = "{\"username\":\"test2\",\"passwd\":\"test\",\"company\":\"哈哈网络\",\"child_number\":10}")UserEntity user,HttpServletRequest request) {return ResSuccessTemplate.builder().build();}@ApiOperation("获取用户")@ApiImplicitParams({@ApiImplicitParam(name = "userid", value = "用户的id", required = true)})@GetMapping("/getUser/{userid}")public ResponseTemplate GetRootChildNumberMax(@PathVariable("userid") int userid) {return ResSuccessTemplate.builder().build();}}

@ApiModel@Mapperpublic class UserEntity {@ApiModelProperty(hidden= true)private int id;@ApiModelProperty(hidden= true)private String username;@ApiModelProperty(value = "需求主题")private String age;@ApiModelProperty(hidden= true)@JsonProperty(access = JsonProperty.Access.WRITE_ONLY)private String passwd;}

二、SpringBoot集成并自定义Swagger访问路径

上面的集成后，访问地址为：http://localhost:8030/swagger-ui.html

在一些经过网关访问时要加上某个自定义地址，当然可以通过 spring.jersey.application-path来实现，但有些情况不好设置全局的地址时，就可以用下面方式。

下面将Swagger访问地址修改为：

http://localhost:8030/my/index.html

下载swagger-ui

/swagger-api/swagger-ui/tree/v3.18.3

@Controller@RequestMapping("/my")public class SwaggerController {@GetMapping("/v2/api-docs")public void swagger(HttpServletRequest request, HttpServletResponse response){String url = "/v2/api-docs";System.out.println(url);try {request.getRequestDispatcher(url).forward(request,response);} catch (Exception e) {e.printStackTrace();}}}

将解压后打包好的dist文件夹改名称为my，并将修改后的文件夹复制到static下。修改static/my/index.html

将 url: "https://petstore.swagger.io/v2/swagger.json"修改为：url: "/my/v2/api-docs"

修改引用：

<script src="/my/swagger-ui-bundle.js"> </script><script src="/my/swagger-ui-standalone-preset.js"> </script>

5. 重新打开项目便以生效。