Swagger使用学习

桃扇骨 2023-09-28 08:56 10阅读 0赞

### 一、什么是Swagger? ###

最流行的API框架，是**一款RestFul风格 API文档的在线自动生成工具**，能使得API文档和API定义同步更新。

讲得简单些，现在是前后端分离时代，前端可以不再依赖后端就能直接运行，而实现前后端交互的过程就是后端在控制层提供一个个API接口，前端通过这些API接口来获取对应的Json数据。现在面临一个问题，如果前端需求发生变化，比如数据表要添加一个字段，前端是很容易做到的，可后端修改起来却很麻烦，尤其是当需求不断变化，而前后端又不能及时沟通，就会使得项目开发延期。而Swagger就是用来解决这个问题的，它能让前端团队及时知道后端的API有哪些变化，从而及时进行修改调整。

### 二、如何使用Swagger? ###

这里简单介绍一下在Spring Boot 里使用Swagger的步骤

1、新建一个Spring Boot-web工程，导入Swagger依赖

<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、编写一个Hello工程，创建一个配置类来配置Swagger ，具体配置内容后面在说

@Configuration
    @EnableSwagger2  //开启swagger2
    public class SwaggerConfig {
    }

3、在浏览器里输入以下URL来测试网站是否成功集成了Swagger：[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

4、在之前创建的配置类里配置Swagger

配置Swagger扫描的对象：

//配置了swagger的Docket的bean实例
        @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())//swagger基本信息(标题、介绍、联系URL...),默认使用自定义的，也可以自己新建apiInfo()
                    .groupName("xlyoung")//配置API的分组，默认为default
                    .enable(false) //enable是否启用默认为true,swagger如果为false，则Swagger不能在浏览器中访问
                    .select()
                    //RequestHandlerSelectors，配置要扫描接口的方式
                    //-->basePackage，指定要扫描的包
                    //-->any()，扫描全面
                    //-->none()，都不扫描
                    //-->withClassAnnotation，扫描类上的注解
                    //-->withMethodAnnotation，扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.zzq.swagger.controller"))
                    //paths过滤什么路径
                    .paths(PathSelectors.ant("/zzq/**"))
                    .build();
        }
    
    
        //如何去配置多个分组，只需要配置多个Docket实例就行
        @Bean
        public Docket docket1(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("A");
        }
        @Bean
        public Docket docket2(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("B");
        }
        @Bean
        public Docket docket3(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("C");
        }

5、我们可以在实体类上加一些注释的注解，方便对生成的API文档进行说明和理解

@ApiModel("用户实体类")//该注解用来给类注释，方便用户理解，不加它swagger也会获取到该对象
    public class User {
        @ApiModelProperty("姓名")//该注解用来给属性注释，方便用户理解，不加它swagger也会获取到该对象
        private String name;
        @ApiModelProperty("密码")
        private String password;
    
        //get/set/构造方法省略
    }

同样的，我们也可以在控制层里的方法上加上相关注解来为其做注释：

@ApiOperation("保存用户")//注意只能在方法上加这个注解，而不能在类上加
    @PostMapping("/saveUser")
    public String saveUser(@ApiParam("用户") @RequestBody User user){
        return "保存成功！姓名："+user.getName()+"，密码："+user.getPassword();
    }

### 三、Swagger的测试功能 ###

可以在 http://localhost:8080/swagger-ui.html 页面里对各个API进行在线测试

[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html