五分钟上手swagger

灰太狼 2022-12-11 14:00 160阅读 0赞

![20210104125743157.png][]

### 文章目录 ###

*   *  一、swagger是什么？
     *  二、使用swagger
     *   *  1、引入依赖
         *  2、配置
         *   *  2.1、配置swagger配置
             *  2.2、配置swagger扫描
             *  2.3、配置swagger2设置分组
             *  2.4、实体类设置
             *  2.5、接口测试
     *  三、拓展

## 一、swagger是什么？ ##

swagger是一种基于Rest 风格的api文档开发工具，我们常常应用于前后端分离项目，解决由于前后端分离导致的数据接口不一致问题，有效的减少前端程序员与后端程序员的打斗次数。

swagger自己是这样介绍swagger的：

1.  Swagger是一组功能强大且易于使用的API开发人员工具套件，适用于团队和个人，可在整个API生命周期（从设计和文档到测试和部署）中进行开发。
2.  Swagger由开放源代码，免费和市售工具共同组成，它使任何人（从技术工程师到街头智能产品经理）都可以构建每个人都喜欢的惊人API。
3.  Swagger由SmartBear Software构建，后者是团队软件质量工具的领导者。SmartBear落后于软件领域的一些知名企业，包括Swagger，SoapUI和QAComplete。

![20201002212241455.png][]

## 二、使用swagger ##

### 1、引入依赖 ###

在`pom.xml`文件中加入依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.7.0</version>
    </dependency>

### 2、配置 ###

主要从这几个方面来配置swagger

> 1、配置swagger配置  
> 2、配置swagger扫描  
> 3、配置swagger2设置分组  
> 4、实体类设置

#### 2.1、配置swagger配置 ####

首先若要使用swagger需要在配置文件上加上`@EnableSwagger2`注解，使用swagger2生效。

以下就是最简单的配置方法

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
        @Bean
        public Docket docket(Environment environment){ 
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
        }
        /** * 配置swagger信息 */
        public ApiInfo apiInfo(){ 
            return new ApiInfo(
                    "教科文",
                    "即使再小的帆也能远航",
                    "1.0",
                    "urn:tos",
                    new Contact("lomtom", "#", "lomtom@qq.com"),
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList<>());
        }
    }

如果你不知道ApiInfo的字段含义，我们可以查看他的构造方法，里面分别是它所代表的含义，这个相信会一点英文的都能够看得懂。

而ApiInfo并没有自己属性的set方法，所以我们只能使用构造方法来进行注入。

1、ApiInfo构造方法
    public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection<VendorExtension> vendorExtensions) { 
        this.title = title;
        this.description = description;
        this.version = version;
        this.termsOfServiceUrl = termsOfServiceUrl;
        this.contact = contact;
        this.license = license;
        this.licenseUrl = licenseUrl;
        this.vendorExtensions = Lists.newArrayList(vendorExtensions);
    }
    2、其中的Contact构造方法
    public Contact(String name, String url, String email) { 
        this.name = name;
        this.url = url;
        this.email = email;
    }

此时无需配置其他的我们也可以直接使用swagger。

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

在我的项目里一共有三个Controller：`LoginController、RegisterController、OssController`  
![20201002222742819.png][]

其中1、红色框框内就是我配置的一些信息，而标注的①②③是我自己的`controller`，额外的④是默认的`controller`，也就是我们访问出错的`/error`页面  
![20201002223044875.png][]

#### 2.2、配置swagger扫描 ####

若我们在开发中不想看到默认的controller或者需要隐藏其他的controller，我们可以使用以下配置

@Bean
        public Docket docket(Environment environment){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
       				 //指定要扫描的包
                    .apis(RequestHandlerSelectors.basePackage("com.lomtom.website"))
                    //过滤路径
    				//.paths(PathSelectors.ant("/admin/**"))
                    .build();
        }

其中，apis参数中RequestHandlerSelectors一共有五种配置：

//1、basePackage：指定要扫描的包
    //2、any()：扫描全部
    //3、none()：都不扫描
    //4、withClassAnnotation()：类上的
    //5、withMethodAnnotation()：方法的

而.paths(PathSelectors.ant("/admin/\*\*"))，指的是我只扫描`/admin/`路径下的所有请求。

#### 2.3、配置swagger2设置分组 ####

当我们在实际的开发中，一个项目往往由多个开发人员共同协作完成的，而swagger恰好可以在这方面解决这一问题。

@Bean
     public Docket docket1(Environment environment) { 
         return new Docket(DocumentationType.SWAGGER_2)
                 .groupName("ou");
     }
    
     @Bean
     public Docket docket2(Environment environment) { 
         return new Docket(DocumentationType.SWAGGER_2)
                 .groupName("yang");
     }

我们再在原来的基础上加上两个Docket，当然实际中我们需要配置的往往不会这么简单，这里只是举例说明。

可以看到，在原来的分组中多了两个组，这样我们的程序员就可以只查看自己的负责的接口了。  
![20201002224135724.png][]

#### 2.4、实体类设置 ####

我们可以在实体类中对我们的model对象进行一些说明。`@ApiModel`对实体类的说明，`@ApiModelProperty`对类的属性的说明。

@Data
    @TableName("admin_user")
    @ApiModel("管理员用户类")
    public class AdminUserEntity { 
    
        @TableId(type = IdType.AUTO)
        private Long id;
    
        @ApiModelProperty("用户名")
        private String userName;
    
        private String password;
    
        private Date creatTime;
    
    }

除此之外：  
**swagger的常用API**

1.  api标记  
    Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

1.  ApiOperation标记  
    ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
              value = "Find purchase order by ID",
              notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
              response = Order,
              tags = { "Pet Store"})

1.  ApiParam标记  
    ApiParam请求属性,使用方式：

public R save(@RequestBody @ApiParam(value = "save user", required = true)  User user)

1.  ApiResponse  
    ApiResponse：响应配置，使用方式：  
    @ApiResponse(code = 400, message = “Invalid user supplied”)
2.  ApiResponses  
    ApiResponses：响应集配置，使用方式：  
    @ApiResponses(\{ @ApiResponse(code = 400, message = “Invalid Order”) \})
3.  ResponseHeader  
    响应头设置，使用方法  
    @ResponseHeader(name=“head1”,description=“response head conf”)

例如：我在我的上传文件的controller上加上注解说明

@Api(tags = "OSS管理")
    @RestController
    public class OssController { 
    
        @ApiOperation("获取上传图片的api凭证")
        @GetMapping("/oss/upload")
        protected R poliocy(HttpServletRequest request, HttpServletResponse response) { 
        
        }
    }

这样就可以对我们的接口进行中文说明。  
![20201002225133390.png][]

#### 2.5、接口测试 ####

swagger还为程序员提供了接口的测试功能，例如：测试login接口，填上需要的信息，点击下方的`Try it out`进行测试。  
![20201002225438341.png][]  
从显示的数据中可以清晰地到看到我们所需要的信息：请求地址、请求头、请求体、状态码、回应头信息。  
![20201002225639935.png][]

## 三、拓展 ##

这里有这样一个问题，也常常会作为面试题出现：

问题：怎么使swagger在开发环境下使用，发布时不使用？

答：需要建立好几个`springboot`配置文件，例如`application.yml`、`application-pro.yml`、`application-dev.yml`，分别用于默认、部署后、开发的环境中。在`application.yml`指定当前使用的是哪一个

spring:
      profiles:
        active: dev

然后，再在swagger配置中配置，如果当前环境使用的是dev的配置文件，就是用`enable(flag)`，来关闭swagger功能。

这样就能使项目上线后不暴露接口，有效的提高安全性。

@Bean
        public Docket docket(Environment environment){ 
            Profiles profiles = Profiles.of("dev");
            boolean flag = environment.acceptsProfiles(profiles);
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("lomtom")
                    .apiInfo(apiInfo())
                    .enable(flag);
        }

> 总的来说，swagger是一个很好用的api文档工具，并且上手难度不高，最关键的是能减少前后端程序员的打斗次数，你值得拥有。

> [1、swagger 介绍及两种使用方法][1_swagger]

关注公众号：**博奥思园**  
还是那句话：**你的支持是我前进的最大动力**

![20200405094243147.png][]

[20210104125743157.png]: /images/20221123/aba6180f0b4f4c2f9c63e50161a3b7f2.png
[20201002212241455.png]: /images/20221123/3473d0b586294f9c85610e23aa6c454d.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[20201002222742819.png]: /images/20221123/eedd29ae0d3846dea5cab104070d5864.png
[20201002223044875.png]: /images/20221123/48dfa213df314c4c826972f31e31d244.png
[20201002224135724.png]: /images/20221123/1dabd5c9a5a048089cf6499ae8f0c579.png
[20201002225133390.png]: /images/20221123/127fa3449c5e475d884ad20ef41685a4.png
[20201002225438341.png]: /images/20221123/694e7eee3e694af09134c32f5c092b9a.png
[20201002225639935.png]: /images/20221123/691869b8a9ca4f59837c95dd746b6632.png
[1_swagger]: https://blog.csdn.net/weixin_37509652/article/details/80094370
[20200405094243147.png]: /images/20221123/829504af8aa74b8e8ae207fdd8d49bf7.png