SpringBoot使用swagger-spring-boot-starter maven依赖包实现Swagger2

前言本文主要介绍SpringBoot框架下，如何使用swagger-spring-boot-starter maven依赖包实现Swagger2适用于对SpringBoot+maven 有一定基础的同学。一、Swagger2是什么？Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的We

kongtong2004

9897人浏览 · 2020-10-02 11:05:09

kongtong2004 · 2020-10-02 11:05:09 发布

前言
本文主要介绍SpringBoot框架下，如何使用swagger-spring-boot-starter maven依赖包实现Swagger2
适用于对SpringBoot+maven 有一定基础的同学。

一、Swagger2是什么？
Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。
Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法、参数和模型紧密集成到服务器的代码，允许Api 来始终保持同步。
Swagger官网：http://swagger.io/
Swagger源码：https://github.com/swagger-api/
二、准备工作
1、JDK1.8
2、SpringBoot2.3.4 + maven3.6.1 项目
3、开发工具：idea2020.2
4、swagger maven依赖版本

    <dependency>
		<groupId>com.spring4all</groupId>
		<artifactId>swagger-spring-boot-starter</artifactId>
		<version>1.9.1.RELEASE</version>
	</dependency>

三、使用步骤
1、创建SpringBoot项目，采用maven管理项目依赖：
idea IDE工具，File -> New -> Module，通过Spring Initializr创建名为meander-swagger的SpringBoot项目。

      创建好的SpringBoot项目结构如下：

在这里插入图片描述

代码清单：
1）POM.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.4.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.meander</groupId>
	<artifactId>meander-swagger</artifactId>
	<version>1.0.0-SNAPSHOT</version>
	<name>meander-swagger</name>
	<description>Swagger Api 示例</description>

	<properties>
		<java.version>1.8</java.version>
		<spring-cloud.version>Hoxton.SR8</spring-cloud.version>
	</properties>

	<dependencies>
		<!-- 引入swagger2依赖包 -->
		<!--<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>-->
		<!-- 引入SpringBoot swagger2 起步依赖包 -->
		<dependency>
			<groupId>com.spring4all</groupId>
			<artifactId>swagger-spring-boot-starter</artifactId>
			<version>1.9.1.RELEASE</version>
		</dependency>
		
		<dependency>
			<groupId>javax.validation</groupId>
			<artifactId>validation-api</artifactId>
			<version>1.1.0.Final</version>
		</dependency>
		<!-- 引入SpringBoot Web 依赖包 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

启动类MeanderSwaggerApplication.java，加注解 @EnableSwagger2Doc：

@EnableSwagger2Doc
@SpringBootApplication
public class MeanderSwaggerApplication {
	public static void main(String[] args) {
		SpringApplication.run(MeanderSwaggerApplication.class, args);
	}
}

3)Swagger配置：因采用yml配置文件，所以不再需要自己编写SwaggerConfig配置类了。

演示接口类
SwaggerController.java

package com.meander.swagger.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;

/**
 * Description:
 *
 * @author sage
 * @date 2020/10/1 14:13
 */
@Api(value = "Swagger演示接口")
@RestController
public class SwaggerController {
    @ApiOperation(notes = "导航页",value = "index")
    @GetMapping("/index")
    public String index( HttpServletRequest request,@ApiParam(name = "userName",value = "用户名",required = true) @RequestParam("userName") String userName){
        System.out.println(request.getServerPort());
        return "欢迎"+userName+"进入首页，请求地址："+request.getRequestURL();
    }

    @ApiOperation("获取用户名")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName",value = "用户名",required = true,paramType="form",dataType="string"),
            @ApiImplicitParam(name="password",value="密码",required=true,paramType="string")
    })
    @PostMapping("/getName")
    public String getName( @RequestParam("userName") String userName,
                           @RequestParam("password") String password){
        return "欢迎你，" + userName;
    }
}

5）配置文件 application.yml ：

###swagger如下都是非必须的配置（实际使用时请根据实际情况配置）
swagger:
  enabled: true
  title: API文档
  description: 舜汭科技|讲武堂
  termsOfServiceUrl: https://meander.net.cn
  contact:
    name: sage
    url: www.meander.net.cn
    email: sage@meander.net.cn
  #接口包扫描路径
  base-package: com.meander.swagger.controller
  #需排除的接口路径
  exclude-path: /error/**

示例源码:
如有需要请留言。
2.成功启动服务后，浏览器直接访问
http://localhost:8080/swagger-ui.html
在这里插入图片描述

可以点击“Try it out”，在线测试api接口，模拟发送请求。
在这里插入图片描述

四：swagger的常用注解
1、Api标记
Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

 @Api(value = "/dept", description = "操作部门相关信息")

2、ApiOperation标记
ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
          value = "方法说明：通过部门编号获取部门信息",
          notes = "接口发布说明",
          response = "Dept"  //接口返回参数类型
          )

3、ApiParam标记
ApiParam请求属性,使用方式：

public ResponseEntity<Dept> createDept(@RequestBody @ApiParam(value = "Dept部门对象", required = true)  Dept dept)

4、ApiResponse
ApiResponse：响应配置，使用方式：

@ApiResponse(code = 400, message = "Invalid dept supplied")

5、ApiResponses
ApiResponses：响应集配置，使用方式：

  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Dept") })

6、ResponseHeader
响应头设置，使用方式：

@ResponseHeader(name="head1",description="response head conf")

   以上就是今天要讲的内容，本文仅仅简单介绍了swagger的使用，更多内容可参考官网资料。

六、问题汇总
1、通过扫描包路径的方式获取api接口方法，这里的包路径不支持如下这种带* 或 ** 的通配符

RequestHandlerSelectors.basePackage("com.meander.*.controller")

2、如果浏览器访问出现如下页面：

在这里插入图片描述
错误提示：

Unable to infer base url. This is common when using dynamic servlet
registration or when the API is behind an API Gateway. The base url 
is the root of where all the swagger resources are served. For e.g. 
if the api is available at http://example.org/api/v2/api-docs then 
the base url is http://example.org/api/. Please enter the location 
manually:

主要的可能原因是：扫描不到swaggerConfig配置类所在的路径。
解决方案：
在启动类的注解上指定要扫描的包路径（SwaggerConfig类所在的包的路径）：

@SpringBootApplication(scanBasePackages = "com.meander.swagger")

2）项目有拦截器，将swagger ui资源文件拦截了。
解决方案：放行 /webjars, /swagger-resources, /v2/api-docs 这三个路径。
3、页面不显示接口，提示信息
No operations defined in spec! 在这里插入图片描述

原因：swaggerConfig配置类中如下加粗代码部分指定的包路径配置错误，导致无法扫描到API接口方法。
解决方案：修改成自己的包路径
.apis(RequestHandlerSelectors.basePackage(“com.meander.swagger.controller”)

@Bean
    public Docket createRestApi() {
        //这里采用包含注解的方式来确定要显示的接口
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                //通过方法上带有ApiOperation注解获取api接口信息
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //这里采用包扫描的方式来确定要显示的接口
                .apis(RequestHandlerSelectors.basePackage("com.meander.swagger.controller"))
                .paths(PathSelectors.any()).build();
    }