Swagger最基础整理(附赠项目源码和视频)

我不是女神ヾ 2023-09-29 14:26 13阅读 0赞

### 文章目录 ###

*   *  一、Swagger简介
     *   *  1、Swagger简介
         *  2、官网
         *  3、项目代码
         *  4、参考视频
     *  二、初始化Swagger项目
     *   *  1、pom文件
         *  2、Swagger配置类
         *  3、Controller接口
         *  4、页面展示
     *  三、Swagger配置
     *   *  1、枚举参数配置
         *   *  1.1 RequestHandlerSelectors
             *  1.2 PathSelectors
         *  2、Swagger基本信息配置
         *  3、配置扫描包位置
         *  4、配置Swagger开关
         *  5、配置多个分组
         *  6、自定义注解不扫描包
     *  四、API中使用Swagger
     *   *  1、Swagger注解
         *  2、Controller中使用
         *   *  2.1 @Api( )
             *  2.2 @ApiOperation()-类/方式
             *  2.3 @ApiParam()
             *  2.4 @ApiResponses()
             *  2.5 @ApiImplicitParams()
             *  2.6 @ApiIgnore()
         *  3、model中使用Swagger
         *   *  3.1 @ApiModel()
             *  3.2 @ApiModelProperty()

--------------------

## 一、Swagger简介 ##

### 1、Swagger简介 ###

Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。

Swagger工具包括的组件：

Swagger Editor ：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。

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

Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

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

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

### 2、官网 ###

[官网][Link 1]

https://swagger.io/

### 3、项目代码 ###

[CSDN][]

https://download.csdn.net/download/weixin_44624117/85357475

### 4、参考视频 ###

[视频][Link 2]

https://www.bilibili.com/video/BV1yi4y1F7KP

[讲义][Link 3]

https://download.csdn.net/download/weixin_44624117/85374341

## 二、初始化Swagger项目 ##

### 1、pom文件 ###

**SpringBoot集成Swagger** => **springfox**，两个jar包

*  **Springfox-swagger2**
 *  swagger-springmvc

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

### 2、Swagger配置类 ###

package com.lydms.swaggerdemo.config;
    
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        
    }

或者在启动类上加上`@EnableSwagger2`(效果相同)：

会扫表当前类所在包，以及子包中所有类型的注解。

package com.lydms.swaggerdemo;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @EnableSwagger2
    @SpringBootApplication
    public class SwaggerDemoApplication {
        
    
        public static void main(String[] args) {
        
            SpringApplication.run(SwaggerDemoApplication.class, args);
        }
    }

### 3、Controller接口 ###

package com.lydms.swaggerdemo.web;
    
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    @RequestMapping("/test")
    public class UserController {
        
        
        @RequestMapping("/user")
        public String addUser() {
        
            return "hello world";
        }
    }

### 4、页面展示 ###

http://ip:port/swagger-ui.html

![请添加图片描述][69f95df90b324093ba11e2d75a2bde70.png]

## 三、Swagger配置 ##

### 1、枚举参数配置 ###

![请添加图片描述][631e12d9654540b4b7ec54fbe3277148.png]

#### 1.1 RequestHandlerSelectors ####

.apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo"))

*  `any()`

//	扫描所有，项目中的所有接口都会被扫描到
    RequestHandlerSelectors.any()

*  `none()`

//	不扫描接口(RequestHandlerSelectors配置如何扫描接口)
    RequestHandlerSelectors.none()

*  `basePackage()`

//	根据包路径扫描接口
    RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")

*  `withMethodAnnotation()`

//	通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
    RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)

*  `withClassAnnotation()`

//	通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
    RequestHandlerSelectors.withClassAnnotation(RestController.class)

#### 1.2 PathSelectors ####

*  `any()`

//	
    PathSelectors.any()

*  `none()`

//	
    PathSelectors.none()

*  `ant()`

//	paths()。过滤什么路径
    PathSelectors.ant("/test/**")

*  `regex()`

//	通过正则表达式路径url，进行文档生成
    PathSelectors.regex("/test")

### 2、Swagger基本信息配置 ###

*  `Docket`：摘要对象，通过对象配置描述文件的信息。
 *  `apiInfo`：设置描述文件中info。参数类型`ApiInfo`。
 *  `select()`：返回`ApiSelectorBuilder`对象，通过对象调用build()可以创建Docket对象
 *  `ApiInfoBuilder`：ApiInfo构建器。

//Swagger信息配置
    @Bean
    public Docket docket() {
        
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo());
    }
    
    //配置文档信息
    private ApiInfo apiInfo() {
        
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfoBuilder()
                .title("Swagger学习") // 标题
                .description("学习演示如何配置Swagger") // 描述
                .version("v1.0") // 版本
                .termsOfServiceUrl("http://terms.service.url/组织链接") // 组织链接
                .contact(contact)   // 联系人信息
                .license("Apach 2.0 许可")    // 许可
                .licenseUrl("许可链接") // 许可连接
                .extensions(new ArrayList<>())  // 扩展
                .build();
    }

配配置后展示：

![请添加图片描述][5de2eecdacf2448ab7b643edeb9549fb.png]

### 3、配置扫描包位置 ###

配置扫描方式：

*  `select()`：
 *  `paths()`：过滤接口的路径
 *  `apis()`方法设置哪个包中内容被扫描

//Swagger信息配置
    @Bean
    public Docket docket() {
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .select()   // 通过.select()方法获取Docket中的选择器，去配置扫描接口。RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")) // 根据包路径扫描接口
                .apis(RequestHandlerSelectors.any())    // 扫描所有，项目中的所有接口都会被扫描到
                .apis(RequestHandlerSelectors.none())   // 不扫描接口(RequestHandlerSelectors配置如何扫描接口)
                // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.ant("/test/**"))   //paths()。过滤什么路径
          			.paths(PathSelectors.regex("/test"))    //通过正则表达式路径url，进行文档生成
                .build();
    }

paths中`PathSelectors`参数：

any() // 任何请求都扫描
    none() // 任何请求都不扫描
    regex(final String pathRegex) // 通过正则表达式控制
    ant(final String antPattern) // 通过ant()控制

### 4、配置Swagger开关 ###

关闭Swagger页面展示

return new Docket(DocumentationType.SWAGGER_2)
      .enable(false); //配置是否启用Swagger，如果是false，在浏览器将无法访问

根据当前所处的环境，决定是否开启Swagger。

指定当前环境(dev环境)

spring.profiles.active=dev

配置代码：

//Swagger信息配置
    public Docket docket(Environment environment) {
        
        // 设置要显示swagger的环境
        Profiles profiles = Profiles.of("dev", "int", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(flag) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")) // 根据包路径扫描接口
                .build();
    }

### 5、配置多个分组 ###

//配置多个分组
    @Bean
    public Docket docket1() {
        
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2() {
        
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3() {
        
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

![请添加图片描述][54e16aba1e5c420d823585e225217833.png]

### 6、自定义注解不扫描包 ###

**自定义注解**

package com.lydms.swaggerdemo.anno;
    
    import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
    
    @Target({
        ElementType.METHOD})
    @Retention(RetentionPolicy.RUNTIME)
    public @interface MySwagger {
        
    
    }

**Swagger配置**

//5、自定义：使用注解，不生成文档
    @Bean
    public Docket docket() {
        
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .select()
                //  注解加载指定方法上不展示(Predicates.not)取反
                .apis(
                        Predicates.not(  //取反
                                RequestHandlerSelectors.withMethodAnnotation(MySwagger.class)	//根据注解配置
                        ))
                .build();
    }

**使用注解**

/**
     * @MySwagger注解：自定义忽略生成Swagger文档
     */
    @MySwagger
    @GetMapping("/testInterface")
    public String notSwagger(int pageNo, int pageSize) {
        
        return "pageNo=" + pageNo + "; pageNo=" + pageSize;
    }

## 四、API中使用Swagger ##

### 1、Swagger注解 ###

`@Api`：用在请求的类上，表示对类的说明

@Api：用在请求的类上，表示对类的说明
      tags="说明该类的作用，可以在UI界面上看到的注解"
      value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

`@ApiOperation`：用在请求的方法上，说明方法的用途、作用

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

`@ApiImplicitParams`：用在请求的方法上，表示一组参数说明

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
      @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
          · header --> 请求参数的获取：@RequestHeader
          · query --> 请求参数的获取：@RequestParam
          · path（用于restful接口）--> 请求参数的获取：@PathVariable
          · div（不常用）
          · form（不常用）
        dataType：参数类型，默认String，其它值dataType="Integer"
        defaultValue：参数的默认值

`@ApiResponses`：用在请求的方法上，表示一组响应

@ApiResponses：用在请求的方法上，表示一组响应
      @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

`@ApiIgnore`: 忽略文档或者忽略方法接口生成

@ApiIgnore: 忽略文档或者忽略方法接口生成

`@ApiModel`：用于响应类上，表示一个返回响应数据的信息

@ApiModel：用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

`@ApiModelProperty`：用在属性上，描述响应类的属性

@ApiModelProperty：用在属性上，描述响应类的属性

![请添加图片描述][c860cd50c1d34c2ca0a1fb49be9f3c47.png]

### 2、Controller中使用 ###

#### 2.1 @Api( ) ####

@Api是类上注解。控制整个类生成接口信息的内容。

*  `tags`：类的名称。可以有多个值，多个值表示多个副本。
 *  `description`：描述，已过时。

@Api(tags = "Swagger测试接口")
    @RestController
    @RequestMapping("/test")
    public class UserController {
        
    }

![在这里插入图片描述][c843e19936a64b748c679b9637ec2873.png]

#### 2.2 @ApiOperation()-类/方式 ####

@ApiOperation写在方法上，对方法进行总体描述

*  `value`：接口描述
 *  `notes`：提示信息

@ApiOperation( value = "新增用户")
    @ApiResponses({
        @ApiResponse(code = 200, message = "OK", response = MyUser.class)
    @PostMapping("/user")
    public MyUser user() {
        
        MyUser myUser = new MyUser();
        myUser.setName("张三");
        myUser.setAge(18);
        myUser.setId("123123123");
        System.out.println(myUser.toString());
        return myUser;
    }

![请添加图片描述][28cdaf0547004e81b45d494554274d27.png]

#### 2.3 @ApiParam() ####

@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。

*  `name`：参数名称
 *  `value`：参数描述
 *  `required`：是否是必须

@GetMapping("/user01")
    public MyUser myUser(@ApiParam(name="用户名",value = "新增用户时提供的用户名",required = true) String username,
                         @ApiParam(name = "密码",value = "新增用户时提供的密码",required = true)String password) {
        
        MyUser myUser = new MyUser();
        myUser.setName(username);
        myUser.setPassword(password);
        return myUser;
    }

![在这里插入图片描述][c90dd367f4204f288a336e86e07b1cc6.png]

#### 2.4 @ApiResponses() ####

*  @ApiOperation(value = “新增用户”)
 *  @ApiResponses(\{@ApiResponse(code = 200, message = “OK”, response = MyUser.class)\})

![请添加图片描述][28cdaf0547004e81b45d494554274d27.png]

#### 2.5 @ApiImplicitParams() ####

`@ApiImplicitParam`用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。

*  `name`：属性名
 *  `value`：描述
 *  `required`：是否是必须的
 *  `paramType`：属性类型
 *  `dataType`：数据类型

/**
     * @ApiImplicitParams：对入参进行解析注解。等同于@ApiParam
     */
    @GetMapping("/testPage")
    @ApiImplicitParams({
        
            @ApiImplicitParam(name = "pageNo", value = "第几页", required = true, paramType = "字符串", defaultValue = "1"),
            @ApiImplicitParam(name = "pageSize", value = "每页显示多少条", required = true, paramType = "字符串", defaultValue = "10")
    })
    public String page(String pageNo, String pageSize) {
        
        return "pageNo=" + pageNo + "; pageNo=" + pageSize;
    }

![在这里插入图片描述][b3e95a970e214eb4af08fd1c29c4d5ac.png]

#### 2.6 @ApiIgnore() ####

@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。

/**
     *   @ApiIgnore：忽略生成API帮助文档
     */
    @ApiIgnore
    @GetMapping("/testInterface")
    public String ignore(int pageNo, int pageSize) {
        
        return "pageNo=" + pageNo + "; pageNo=" + pageSize;
    }

### 3、model中使用Swagger ###

#### 3.1 @ApiModel() ####

@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。

*  `value`：名称
 *  `description`：描述

#### 3.2 @ApiModelProperty() ####

@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。

*  `value`：描述
 *  `name`：重写属性名
 *  `required`：是否是必须的
 *  `example`：示例内容
 *  `hidden`：是否隐藏。

package com.lydms.swaggerdemo.entity;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    @ApiModel(value = "com.lydms.swaggerdemo.entity.MyUser", description = "新增用户参数")
    public class MyUser {
        
        @ApiModelProperty(value = "ID")
        private String id;
        @ApiModelProperty(value = "名称",name = "test",required = true,example = "张三",hidden = true)
        private String name;
        @ApiModelProperty(value = "年龄")
        private int age;
        @ApiModelProperty(value = "密码")
        private String password;
    }

![在这里插入图片描述][c62ecec79c6e4c63a5fa40c2581d0d5e.png]

[Link 1]: https://swagger.io/
[CSDN]: https://download.csdn.net/download/weixin_44624117/85357475
[Link 2]: https://www.bilibili.com/video/BV1yi4y1F7KP
[Link 3]: https://download.csdn.net/download/weixin_44624117/85374341
[69f95df90b324093ba11e2d75a2bde70.png]: https://img-blog.csdnimg.cn/69f95df90b324093ba11e2d75a2bde70.png
[631e12d9654540b4b7ec54fbe3277148.png]: https://img-blog.csdnimg.cn/631e12d9654540b4b7ec54fbe3277148.png
[5de2eecdacf2448ab7b643edeb9549fb.png]: https://img-blog.csdnimg.cn/5de2eecdacf2448ab7b643edeb9549fb.png
[54e16aba1e5c420d823585e225217833.png]: https://img-blog.csdnimg.cn/54e16aba1e5c420d823585e225217833.png
[c860cd50c1d34c2ca0a1fb49be9f3c47.png]: https://img-blog.csdnimg.cn/c860cd50c1d34c2ca0a1fb49be9f3c47.png
[c843e19936a64b748c679b9637ec2873.png]: https://img-blog.csdnimg.cn/c843e19936a64b748c679b9637ec2873.png
[28cdaf0547004e81b45d494554274d27.png]: https://img-blog.csdnimg.cn/28cdaf0547004e81b45d494554274d27.png
[c90dd367f4204f288a336e86e07b1cc6.png]: https://img-blog.csdnimg.cn/c90dd367f4204f288a336e86e07b1cc6.png
[b3e95a970e214eb4af08fd1c29c4d5ac.png]: https://img-blog.csdnimg.cn/b3e95a970e214eb4af08fd1c29c4d5ac.png
[c62ecec79c6e4c63a5fa40c2581d0d5e.png]: https://img-blog.csdnimg.cn/c62ecec79c6e4c63a5fa40c2581d0d5e.png