swagger2的详细笔记

最新推荐文章于 2024-07-04 09:05:13 发布

国富cool

最新推荐文章于 2024-07-04 09:05:13 发布

阅读量212

点赞数

分类专栏：学习笔记文章标签： spring java swagger2

本文链接：https://blog.csdn.net/wgf248679370/article/details/112912042

版权

学习笔记专栏收录该内容

16 篇文章 0 订阅

订阅专栏

一、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配置

@Configuration
public 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", //企业网站
                                "248679370@qq.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;
    }
}

自定义的注解类：

@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中就显示几个。
```
@RestController
@Api(tags = "Swagger学习控制器") //起别名
public class MyController {}
```

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

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

@ApiParam

@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帮助文档。

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

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

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

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

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

@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;
}