2025年swagger2配置security（swagger enable）

大家好，我是讯享网，很高兴认识大家。

一、Swagger简介

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务。

接口文档对于前后端开发人员都非常重要。Swagger可以使得接口文档动态生成

OpenApi：是REST API的api描述格式

- 每个访问地址类型。POST（写）或者GET（读）

- 每个操作的参数，包括输入输出参数

- 认证方法

- 连接信息，声明，使用团队和其他信息。

Open API规范可以使用YAML或JSON格式进行编写。

Open API规范为REST API定义了一个与语言无关的标准接口。

Swagger2的组件：

- Swagger Editor：基于浏览器编辑器，可以在里面编写Open API规范。

- Swagger UI：将Open API规范呈现为交互式API文档，用可视化UI展示描述文件。

- Swagger Codgen：将Open API规范生成为服务器存根和客户端库。

- Swagger Inspector：跟ui有点类似，但是可以返回更多信息，也可以保存请求的实际参数数据。

- Swagger Hub：集成上面所有项目的各个功能。

spring fox：是根据代码生成接口文档，所以生成进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。

讯享网

二、Swagger-UI用法

xml <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>

在启动类上添加一个注解

java@EnableSwagger2 //springfox的注解，开启Swagger2相关技术的开启//会扫描当前类所在的包以及子包中所有类型当中的注解。做Swagger文档的定值

可以通过 localhost:8080/Swagger-ui.html来访问Swagger文档

Swagger-ui可以帮我们做请求的模拟处理（类似于postman）

三、Swagger2配置

java@Configurationpublic class SwaggerConfig { / * 创建Docket类型的对象，并使用spring容器管理 * Docket是Swagger的全局配置对象 * * @return */ @Bean public Docket docket() { Docket docket = new Docket(DocumentationType.SwagGER_2); ApiInfo apiInfo = //api帮助文档的描述信息 new ApiInfoBuilder() .contact(new Contact("王国富Swagger开发文档", //文档的发布者名称 "http://localhost.com", //企业网站 "@.com")) //发布者的电子邮箱 .title("Swagger框架学习帮助文档") .description("Swagger框架学习帮助文档详细描述") .version("1.2") .build(); //构建器模式创建对象 docket.apiInfo(apiInfo);//给docket上下文配置api描述信息 docket .select() //获取Docket中的选择器返回ApiSelectorBuilder.构建选择器如：扫描什么包的注解 .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))//设定扫描那个包（包含子包）中的注解 .apis(Predicates.not(//取反 RequestHandlerSelectors.withMethodAnnotation( //当方法上有什么注解的时候返回true MyAnnotationSwagger.class)) //自定义的注解 )//整体表示方法上有这个注解的时候就不会生成文档在Swagger上面了 .paths(Predicates.or( PathSelectors.regex("/Swagger/.*"), PathSelectors.regex("/.*"), PathSelectors.regex("/Swagger2/.*")) )//通过正则表达式约束生成api文档的路径地址表示上面三个路径的任意一个都会返回true，也就是会在Swagger文档中表现出来 .build();//必须要build，要不然上面不会生效 return docket; }}

自定义的注解类：

java@Target(value = {ElementType.METHOD,ElementType.TYPE}) //描述当前的注解可以定义在什么资源上面//METHOD：方法 TYPE：类型 FILED：属性 PARAMETER：定义在方法参数上@Retention(RetentionPolicy.RUNTIME) //当前注解什么时候有效//RUNTIME：运行时有效 SOURCE：源码有效 CLASS：字节码有效public @interface MyAnnotationSwagger { String value() default "";//自定义注解的属性}

四、Swagger2常用注解

- @Api：描述当前类型生成帮助文档的信息

tags属性其实就是给控制类起别名，在Swagger上显示是别名（可以用中文），定义几个在ui中就显示几个。

java @RestController @Api(tags = "Swagger学习控制器") //起别名 public class MyController {}

- @ApiOperation：给方法描述 value没有默认

java @ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用-处理POST请求方法") @PostMapping("/post") public String post(){ return "post"; }

- @ApiParam

java @ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用-处理POST请求方法") @PostMapping("/post") public String post(@ApiParam(name = "用户名",value = "新增用户时提供的用户名",required = true) String username, @ApiParam(name = "密码",value = "新增用户时提供的密码",required = true) String password){ return "post"; }

- @ApiIgnore ：忽略，当前注解描述的方法或者类型，不生成api帮助文档。

java @ApiIgnore @GetMapping("/get") public String get(){ return "get"; }

- @ApiImplicitParam：对方法的参数进行描述

java @GetMapping("/test") @ApiImplicitParam(name = "a",value = "test方法的参数a的描述",required = false,paramType = "字符串",dataType = "名值对") public String test(String a,String b){ return "test"; }

- @ApiModel：描述一个实体类型，当该实体类型会成为api帮助问你当方法的返回值类型的时候，则次注解会被解析。

@ApiModelProperty：对实体类的属性进行描述

java @ApiModel(value = "用户类实体",description = "存储用户数据") @Data @AllArgsConstructor @NoArgsConstructor public class User { @ApiModelProperty(value = "主键",name = "主键（id）",required =false,example = "1",hidden = false) private Integer id; private String username; private String password; }

2025年swagger2配置security（swagger enable）

相关推荐