SpringBoot项目中使用Swagger2，及其详细介绍注解

最新推荐文章于 2024-07-24 20:28:15 发布

@Meto

最新推荐文章于 2024-07-24 20:28:15 发布

阅读量2k

点赞数

本文链接：https://blog.csdn.net/qq_45830276/article/details/126556165

版权

SpringBoot项目中使用Swagger2，及其详细介绍注解

文章目录

SpringBoot项目中使用Swagger2，及其详细介绍注解

什么是swagger2

编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。

1、swagger2的配置

1.1、引入Swagger2依赖

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--swagger ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--swagger2  增强版接口文档-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>

1.2、编写SwaggerConfig配置文件

package com.melody.rest.config;

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;

/**
 * @ClassName: SwaggerConfig
 * @Description: Swagger配置了类
 * @Author: liu-hao
 * @Date: 2020-12-10 10:18
 * @Version: 1.0
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // api接口包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.melody.rest.restcontroller";
    // 接口文档版本
    public static final String VERSION = "1.0.0";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于分组功能，也可以不配置
                .groupName("eleprice-service")
                //注册整体api信息
                .apiInfo(apiInfo())
                //swagger功能是否启用，可以通过配置设置，也可以先写死
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("学习系统")
                .description("接口文档")
                .contact(new Contact("张三", "http://liushili.icu", "xxxxx@163.com"))
                .version(VERSION)
                .build();
    }
}

注意：更改成项目中的controller

在这里插入图片描述

1.3、配置类及其参数说明

（1）创建Docker类型的对象，并使用spring容器管理。Docker是Swagger中的全局配置对象

DocumentationType.SWAGGER_2：给Docket一个类对象，知道是那一个版本的

apiInfo()：API文档的描述信息，参数是一个ApiInfo类对象，使用bulid()构建器来创建

private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("平台接口 v1.0")
               .description("平台接口")
               .contact(contact)
               .version("1.0")
               .build();
   }
12345678

（2）contact()：配置swagger文档的主体内容，里面填写也是一个类对象，类对象最多可以三个参数，发布者名称，文档发布者的网站url地址（企业网站），文档发布者的电子邮箱地址

private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");
1

title()：标题 description()：描述信息 .version()：版本信息

对应如下内容

select()：获取Docker中的选择器，返回ApiSelectorBuilder。构建选择器。如扫描什么包的注解

apis()：后面是RequestHandlerSelectors的类下的(Predicate)规则，规定扫描那些包的注解，默认是启动类及其子包下的注解

RequestHandlerSelectors类下有几个静态方法（举例三个）

basePackage()：后面填写包名的具体地址，会扫描改包及其子包的注解
docker.apis(RequestHandlerSelectors.basePackage("com.xxx"))
1

any()：为任何接口生成API文档

none()：任何接口都不生成接口文档

path()：使用正则表达式，约束生成Api文档的路径地址，后面填写过滤（通过）的路径

//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*页面或者admin路径下的所有页面都支持（or任意满足起一就通过）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

2、swagger2 注解整体说明

2.1、请求类的描述

注解	说明
@Api	对请求类的说明

2.2、方法和方法参数的描述

注解	说明
@ApiOperation	方法的说明
@ApiImplicitParams	方法参数的说明；
@ApiImplicitParam	用于指定单个参数的说明。

2.3、方法的响应状态的描述

注解	说明
@ApiResponses	方法返回值的说明；
@ApiResponse	用于指定单个参数的说明。

2.4、对象的描述

注解	说明
@ApiModel	用在JavaBean类上，说明JavaBean的整体用途
@ApiModelProperty	用在JavaBean类的属性上面，说明此属性的的含议

3、请求类的描述

3.1、@Api：请求类的说明

@Api：放在 请求的类上。与 @Controller 并列，说明类的作用，如用户模块，订单类等。
	tags="说明该类的作用"
	value="该参数没什么意义，所以不需要配置"
123

3.2、示例：

@Api(tags="订单模块")
@Controller
public class OrderController {

}
12345

@Api 其它属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径
position	如果配置多个Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏

4、方法和方法参数的描述

4.1、@ApiOperation：方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"
	value="说明方法的作用"
	notes="方法的备注说明"
123

4.2、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
	@ApiImplicitParam：对单个参数的说明	    
	    name：参数名
	    value：参数的说明、描述
	    required：参数是否必须必填
	    paramType：参数放在哪个地方
	        · query --> 请求参数的获取：@RequestParam
	        · header --> 请求参数的获取：@RequestHeader	      
	        · path（用于restful接口）--> 请求参数的获取：@PathVariable
	        · body（请求体）-->  @RequestBody User user
	        · form（普通表单提交）	   
	    dataType：参数类型，默认String，其它值dataType="Integer"	   
	    defaultValue：参数的默认值

4.3、示列：

@Api(tags="用户模块")
@Controller
public class UserController {

	@ApiOperation(value="用户登录",notes="这里是备注")
	@ApiImplicitParams({
		@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
	})
	@PostMapping("/login")
	public JsonResult login(@RequestParam String mobile, @RequestParam String password,	@RequestParam Integer age){
		//...
	    return JsonResult.ok(map);
	}
}

5、对象的描述

5.1、@ApiModel：对象的整体说明

@ApiModel 经常用于请求的入参对象和响应返回值对象的描述。

入参是对象，即 @RequestBody 时，用于封装请求（包括数据的各种校验）数据；
返回值是对象，即 @ResponseBody 时，用于返回值对象的描述。

@ApiModel(description = "用户登录")
public class UserLoginVO  implements  Serializable {

}
1234

5.2、@ApiModelProperty 对象中每个参数的说明

@ApiModelProperty 用于每个属性上面，说明属生的含义。

@ApiModel
public class UserLoginVO  implements  Serializable {

	@ApiModelProperty(value = "用户名",required=true)	
	private String username;	
}
123456

5.3、示例：

入参是对象，即 `@RequestBody` 时，用于封装请求

@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {

	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value = "用户名",required=true)	
	private String username;

	@ApiModelProperty(value = "密码",required=true)	
	private String password;
	
	// getter/setter省略
}
ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {

	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value = "用户名",required=true)	
	private String username;

	@ApiModelProperty(value = "密码",required=true)	
	private String password;
	
	// getter/setter省略
}

@Meto

关注

0
点赞
踩
11

收藏

觉得还不错? 一键收藏
0
评论
SpringBoot项目中使用Swagger2，及其详细介绍注解

编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。
复制链接

扫一扫