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

ha_lydms

发布于 2023-08-10 08:16:42

3010

发布于 2023-08-10 08:16:42

文章被收录于专栏：学习内容

一、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、官网

官网

https://swagger.io/

3、项目代码

CSDN

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

4、参考视频

视频

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

讲义

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

二、初始化Swagger项目

1、pom文件

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

Springfox-swagger2
swagger-springmvc

<!--swagger-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<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

三、Swagger配置

1、枚举参数配置

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();
}

配配置后展示：

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");
}

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：用在属性上，描述响应类的属性

2、Controller中使用

2.1 @Api( )

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

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

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

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

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

2.4 @ApiResponses()

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

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

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

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