Swagger2和SpringBoot的整合

已于 2023-10-11 21:10:41 修改
阅读量59 收藏
点赞数
分类专栏： SpringCloudAlibaba 文章标签： spring boot 后端 java
于 2023-09-24 19:11:09 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_42113716/article/details/133247816
版权

在这里插入图片描述
在这里插入图片描述

1.创建SpringBoot项目swagger2

在这里插入图片描述

2.在项目的pom文件中引入相关依赖

<?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.2.1.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.cloud</groupId>
	<artifactId>swagger2</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>swagger2</name>
	<description>swagger2</description>
	<properties>
		<java.version>1.8</java.version>
	</properties>
	<dependencies>

		<!--swagger-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
		</dependency>
		<dependency>
			<groupId>org.apiguardian</groupId>
			<artifactId>apiguardian-api</artifactId>
			<version>1.1.2</version>
		</dependency>

	</dependencies>

	<build>
		<plugins>

			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.8.1</version>
				<configuration>
					<source>1.8</source>
					<target>1.8</target>
					<encoding>UTF-8</encoding>
				</configuration>
			</plugin>

		</plugins>
	</build>

</project>

2.在项目中创建实体类

package com.cloud.eneity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.*;

@Data
@Setter
@Getter
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description="员工实体")
public class User {
    @ApiModelProperty(value="员工姓名")
    private String name;
    @ApiModelProperty(value="员工年龄")
    private Integer age;
    @ApiModelProperty(value="员工住址")
    private String addr;

}

package com.cloud.eneity;

public class Contact{
    private String name;
    private String url;
    private String mail;
    public Contact(String name, String url, String mail) {
        this.name = name;
        this.url = url;
        this.mail = mail;
    }
}

4.在项目中，创建controller类

package com.cloud.controller;

import com.cloud.eneity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/admin")
@Api(description="测试类")
public class DemoController {

    @RequestMapping("getUser")
    @ApiOperation("方法描述")
    public User getUser(@ApiParam("参数描述") User u){

        User user = new User();

        user.setName(u.getName());
        user.setAge(u.getAge());
        user.setAddr(u.getAddr());
        return  user;
    }

}

5.在项目中，创建Swagger的配置类

创建包com.cloud.config，在包里创建配置类Swagger2Config。

package com.cloud.config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Configuration
@EnableSwagger2
@Component
public class Swagger2Config {

    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }
    //三、Swagger2常用配置和注解 
    //1.对文档的整体添加页面标题、描述信息、创建人等信息
    @Bean
    public ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
                //页面标题
                .title("后台管理系统-API文档")
                //描述信息
                .description("本文档描述了后台管理系统微服务接口定义")
                //版本号
                .version("1.0")
                //创建人
                .contact(new Contact("张三","http://localhost:8080/","123456@163.com"))
                .build();
    }

}

6.通过地址访问测试: http://localhost:8080/swagger-ui.html

1、使用后效果如下

在这里插入图片描述
在这里插入图片描述

2.控制层常用的注解

@Api 使用位置在类上，描述介绍整个类

@ApiOperation 使用位置在方法上，用来介绍方法

@ApiParam 使用位置在参数上，用来介绍参数

在这里插入图片描述

package com.cloud.controller;

import com.cloud.eneity.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/admin")
@Api(description="测试类")
public class DemoController {

    @RequestMapping("getUser")
    @ApiOperation("方法描述")
    public User getUser(@ApiParam("参数描述") User u){

        User user = new User();

        user.setName(u.getName());
        user.setAge(u.getAge());
        user.setAddr(u.getAddr());
        return  user;
    }

}

3.使用后的效果如下：

在这里插入图片描述
在这里插入图片描述
在这里插入图片描述

4.在modle类上常用的注解

@ApiModel使用位置在modle类上，用来介绍实体类

@ApiModelProperty 使用位置在modle类的属性上，用来介绍解释属性

在这里插入图片描述

package com.cloud.eneity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.*;

@Data
@Setter
@Getter
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description="员工实体")
public class User {
    @ApiModelProperty(value="员工姓名")
    private String name;
    @ApiModelProperty(value="员工年龄")
    private Integer age;
    @ApiModelProperty(value="员工住址")
    private String addr;

}

使用后的效果如下：

在这里插入图片描述
在这里插入图片描述

相关注解补充：

一、接口开发规范

（一）Api请求及响应规范

为了严格按照接口进行开发，提高效率，对请求及响应格式进行规范化。

get 请求时，采用key/value格式请求，SpringMVC可采用基本类型的变量接收，也可以采用对象接收。

Post请求时，可以提交form表单数据（application/x-www-form-urlencoded）和Json数据

（Content/Type=application/json），文件等多部件类型（multipart/form-data）三种数据格式，

SpringMVC接收Json数据

使用@RequestBody注解解析请求的json数据。

响应结果统一信息为：是否成功、操作代码、提示信息及自定义数据。

5、响应结果统一格式为json。

二）Api定义约束

Api定义使用SpringMVC来完成，由于此接口后期将作为微服务远程调用使用，在定义接口时有如下限制：

1、@PathVariable 统一指定参数名称，如：@PathVariable(“id”)

2、@RequestParam统一指定参数名称，如：@RequestParam（“id”）

二、接口测试

一）Swagger介绍

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。（https://github.com/OAI/OpenAPI-Specification）

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。 (https://swagger.io/)

Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。

二）Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数

@ApiImplicitParam属性：

在这里插入图片描述

懂你技术
关注
专栏目录
Spring boot 整合Swagger2
adayan_2015的博客
12-06 496
swagger2的使用
（一）springboot整合之swagger2（详细）
热门推荐
weixin_58993861的博客
02-07 1万+
1.新建springboot项目 2.引入maven依赖 <!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version> 2.9.2</version>
springboot项目整合swagger2
weixin_58443365的博客
10-16 233
简单的springboot整合swagger2的
swagger2整合springboot
DYZ的博客
04-26 269
1.导入pom文件： <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency&g...
Swagger2整合SpringBoot
qq_42153997的博客
08-26 158
Swagger2整合SpringBoot Swagger2和SpringBoot的整合,并详细介绍各注解的使用与功能 废话不多数直接撸代码 第一步 日常导入依赖 我的项目时聚合工程,所以版本在父依赖中 <!-- swagger2的依赖 --> <dependency> <groupId>io.springfox</groupId> &...
Swagger2整合Spring Boot（一步到位）
ggjklncffd的博客
08-01 139
代码】Swagger2整合SpringBoot（一步到位）
springboot整合swagger2实例
02-28
SpringBoot整合Swagger2实例详解 在现代Web开发中，API文档的重要性不言而喻，它为开发者提供了清晰的接口说明，使得开发、测试和维护工作更加高效。Swagger2是一款流行的API文档工具，它能自动生成RESTful API的...
Swagger2整合Springboot
10-09
Swagger2整合Springboot详解 随着软件开发的日益复杂化，编写和维护接口文档变得越来越重要。Swagger是一个流行的API文档生成工具，能够快速帮助开发者编写最新的API接口文档。下面，我们将详细介绍如何使用Swagger...
Springboot整合Swagger2
liu_sgxggs的博客
05-18 437
整合时遇到错误可看 1.Swagger2是什么 Swagger是一个RESTUL接口的文档在线自动生成框架和功能测试的框架。根据swagger可以快速的帮助我们编写aip接口文档，间接的提高了团队的开发沟通， 2.创建springboot项目引入swagger依赖 2.1：引入依赖 <!-- Swagger API文档 --> <dependency> <groupId>io.springfox</group.
swagger2学习-整合springboot
ytyDaMoTou的博客
07-01 615
目录一、swagger简介二 springboot集成2.1 导包2.2 添加配置文件SwaggerConfig.java2.3 页面展示2.4 使用方式 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统
springboot整合swagger2
zhenghuishengq的博客
12-31 695
1,概念 Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 2,使用swagger优势 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。 3,接下来开始整合，使用
SpringBoot 整合Swagger2
哈
01-18 3013
第一步：添加Maven依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--Swagger2在线文档--> <!--swagger2本身不支持spring mvc的，springfox把swagger包装了
SpringBoot整合Swagger
早日成为鹏总
03-26 370
第一步：添加相关依赖 <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.5.9.RELEASE</versio...
springboot项目整合Swagger2
JavaEdge全是干货的技术号
01-11 1681
在聚合工程中的父 pom 工程的 pom 文件中添加依赖 <!-- swagger2 配置 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0&l...
【Swagger2】SpringBoot整合Swagger2
meng_xiaohua的博客
07-06 183
前后端分离后，维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。当然这是一种非常理想的状态，实际开发中却很少遇到这样的情况，接口总是在不断的变化之中，有变化就要去维护，做过的小伙伴都知道这件事有多么头大！还好，有一些工具可以减轻我们的工作量，Swagger2就是其中之一，至于其他类似功能但是却收费的软件，这里就不做过多介绍了。本文主要和大伙来聊下在Spring Boot中如何整合Swagger2。 工程创建
swagger和springboot整合
最新发布
09-02
下面我将分别介绍Swagger2和Swagger3的整合步骤。 1. Swagger2与Spring Boot整合的步骤： - 在项目的pom.xml文件中添加Swagger2的Maven依赖。 - 创建一个配置类Swagger2Config.java，用于配置Swagger2的相关参数...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值