SpringBoot项目整合Swagger2

最新推荐文章于 2024-03-23 09:58:44 发布

kongtong2004

最新推荐文章于 2024-03-23 09:58:44 发布

阅读量830

点赞数

分类专栏： JAVA 文章标签： swagger

本文链接：https://blog.csdn.net/kongtong2004/article/details/108895066

版权

JAVA 专栏收录该内容

6 篇文章 0 订阅

订阅专栏

另一种引入Swagger方式（更为简单些）：
SpringBoot使用swagger-spring-boot-starter maven依赖包实现Swagger2

前言
本文主要介绍如何在基于Spring框架中如何使用Swagger2。
适用于对SpringBoot+maven 有一定基础的同学。

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

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

3)Swagger配置类:SwaggerConfig.java

package com.meander.swagger.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger配置类
 *
 * @author sage
 * @date 2020年10月1日19:42:59
 */
@Configuration
@EnableSwagger2
//@ConditionalOnProperty(prefix = "meander", name = "swagger-open", havingValue = "true")
public class SwaggerConfig {

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

    /**
     * Api接口文档信息
     * title:标题
     * description：描述信息
     * version:说明接口版本
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("sage", "http://meander.net.cn", "sage@meander.net.cn");
        return new ApiInfoBuilder().title("舜汭科技-讲武堂")
                                   .description("Api文档")
                                   .termsOfServiceUrl("http://meander.net.cn")
                .contact(contact).version("1.0").build();
    }

}

演示接口类
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 = "SwaggerController")
@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;
    }
}
z

5）配置文件 application.yml ，使用默认生成的即可，无需修改。

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:

主要的可能原因是：
1) 扫描不到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();
    }

kongtong2004

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
SpringBoot项目整合Swagger2

前言本文主要介绍如何在基于Spring框架中如何使用Swagger2。适用于对SpringBoot+maven 有一定基础的同学。一、Swagger2是什么？Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法、参数和模型紧密集成到服务器的代码，允许Api 来始终保持同步，Swagger让部署
复制链接

扫一扫