一、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用法
<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>
在启动类上添加一个注解
@EnableSwagger2 //springfox的注解，开启Swagger2相关技术的开启//会扫描当前类所在的包以及子包中所有类型当中的注解。做Swagger文档的定值
可以通过 `localhost:8080/Swagger-ui.html`来访问Swagger文档
Swagger-ui可以帮我们做请求的模拟处理（类似于postman）
三、Swagger2配置
@Configurationpublic class SwaggerConfig {/* 创建Docket类型的对象，并使用spring容器管理* Docket是Swagger的全局配置对象** @return*/@Beanpublic 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( //当方法上有什么注解的时候返回trueMyAnnotationSwagger.class)) //自定义的注解)//整体表示方法上有这个注解的时候就不会生成文档在Swagger上面了.paths(Predicates.or(PathSelectors.regex("/Swagger/.*"),PathSelectors.regex("/.*"),PathSelectors.regex("/Swagger2/.*")))//通过正则表达式约束生成api文档的路径地址 表示上面三个路径的任意一个都会返回true，也就是会在Swagger文档中表现出来.build();//必须要build，要不然上面不会生效return docket;}}
自定义的注解类：
@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;
}
```
到此这篇swagger2配置security（swagger enable）的文章就介绍到这了,更多相关内容请继续浏览下面的相关推荐文章，希望大家都能在编程的领域有一番成就！版权声明：
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！
转载请注明出处，原文链接：https://www.xkablog.com/rfx/80001.html