五分钟教你学会swagger

一、swagger是什么？

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

swagger自己是这样介绍swagger的：

1. Swagger是一组功能强大且易于使用的API开发人员工具套件，适用于团队和个人，可在整个API生命周期（从设计和文档到测试和部署）中进行开发。

2. Swagger由开放源代码，免费和市售工具共同组成，它使任何人（从技术工程师到街头智能产品经理）都可以构建每个人都喜欢的惊人API。

3. Swagger由SmartBear Software构建，后者是团队软件质量工具的领导者。SmartBear落后于软件领域的一些知名企业，包括Swagger，SoapUI和QAComplete。

二、使用swagger

1、引入依赖

在pom.xml文件中加入依赖

<!--swagger2-->
<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@lomtom.cn"),
                "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 🔗.

在我的项目里一共有三个Controller：LoginController、RegisterController、OssController

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

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，当然实际中我们需要配置的往往不会这么简单，这里只是举例说明。

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

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

2. 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"})

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

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

4. ApiResponse ApiResponse：响应配置，使用方式： @ApiResponse(code = 400, message = “Invalid user supplied”)

5. ApiResponses ApiResponses：响应集配置，使用方式： @ApiResponses({ @ApiResponse(code = 400, message = “Invalid Order”) })

6. 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) {
    
    }
}

这样就可以对我们的接口进行中文说明。

2.5、接口测试

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

三、拓展

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

问题：怎么使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 介绍及两种使用方法 🔗