Swagger的使用

Swagger的使用

1 基础概念

1.1 Swagger的介绍

导语：在平时的开发中，无论是前端还是后端，都或多或少的被接口文档折磨过。前端经常抱怨后端给的接口文档与实际不符，后端又觉得写代码已经够累了，还要相应的更新接口文档，更加麻烦。这个时候，如果有一个工具，可以自动的生成多种格式的接口文档，以及在线调试页面等，就刚好符合开发人的需求。所以Swagger工具就应运而生。

那么问题来了，Swagger到底是什么？

1，Swagger是一款能够让开发人员更好的书写API文档的规范和完整的框架。

2，提供描述、生产、消费和可视化Restful Web Service。

3，是由庞大工具集合支撑的形式化规范。

1.2 Swagger组件的介绍

Swagger Codegen : 通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger Editor ：类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger UI ：提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

2 Swagger 的使用

2.1 添加maven依赖

由于swagger与SpringBoot一起使用的比较多，所以本篇文章所使用的都是SpringBoot与swagger集成。

<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>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.22</version>
</dependency>

2.2 添加配置项

在application.properties中添加对应的配置项，开启Swagger。

swagger.enable=true

2.3 添加配置类

在项目中创建SwaggerConfig.java文件，配置swagger。

@Configuration
@EnableSwagger2
@ConditionalOnProperty(name = "swagger.enable", 
                       havingValue = "true")
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .groupName("dataassets-base")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors
                  .basePackage("Controller对应的包路经"))
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Rest API Docs")
            .description("api info")
            .version("1.0")
            .build();
    }
}

2.4 添加注解

• 在启动类Application.java上添加注解

@EnableSwagger2：表示开启Swagger

@SpringBootApplication
@EnableSwagger2
public class Application {
     public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

• 在Controller类上添加的注解：

@api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@Api(value = "UserController", tags = {"用户模块"})
@RestController
@RequestMapping(value = "/user/")
public class UserController{
    
    @Autowired
    private UserService userService;
    
    @ApiOperation(value = "根据userId获取用户")
    @GetMapping("/queryUserByUserId")
    @ResponseBody
    public DepartmentDTO queryUserByUserId(
        @ApiParam("userId") 
        @RequestParam(value = "userId",required = false) 
        String userId) {
        // 获取满足条件的department
        return userService.getUserByUserId(userId);
    }
}

• 如果请求参数是一个对象时，需要在相应的类上添加注解：

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiModel(value = "UserQuery", description = "查询用户条件")
public class UserQuery implements Serializable {
	
    private static final long serialVersionUID = 1L;
    
    @ApiModelProperty("用户id")
    private String userId;

    @ApiModelProperty("用户名")
    private Long userName;
}

2.5 访问Swagger UI

在浏览器中输入地址 : http://localhost:8080/swagger-ui.html，即可访问Swagger UI。

3 小结

本篇文章简单介绍了Swagger的简单使用，由于纯手打，难免会有纰漏，如果发现错误的地方，请第一时间告诉我，这将是我进步的一个很重要的环节。