Swagger 笔记

1.Swagger简介

作为后端程序开发，我们多多少少写过几个后台接口项目，不管是编写手机端接口，还是目前比较火热的前后端分离项目，前端与后端都是由不同的工程师进行开发，那么这之间的沟通交流通过接口文档进行连接。但往往伴随很多问题，后端程序员认为编写接口文档及维护太花费时间精力，前端的认为接口文档变动更新不及时，导致程序之间相互调用出行问题。那么能简化接口文档的编写直接自动生成吗？当然能！如是乎Swagger这种接口文档在线自动生成工具便孕育而生。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

wagger优点

• 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
• 跨语言性，支持 40 多种语言。
• Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
• 还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试

2.SpringBoot中整合Swagger

1.引入依赖

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

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

    </dependencies>

2.主启动类

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

3.Controller层 

@RestController("zhang")
public class MyController {

    @ApiOperation("Controll")
    @GetMapping(value = "/get")
    public String getTest(String payload){
        System.out.println("zhang");
        return "zhangjunjie";
    }

}

4.Configuration层

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
               return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A")
               .apiInfo(apiInfo())
                .enable(true) //是否开启Swagger
                .select()
                //RequestHandlerSelectors 扫描包的方式
                //basePackage:指定扫描的包
                //any 全部扫描 get
                //withClassAnnotation 扫描类上的注解
                //withMethodAnnotation
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.MyController"))
                //paths 访问路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("乐优商城订单系统")
                .description("乐优商城订单系统接口文档")
                .version("1.0")
                .build();
    }
}

• Docket(DocumentationType.SWAGGER_2) ：这是一个Swagger实例的接口文档版本
• new ApiInfoBuilder() ： 构建Docket需要创建 ApiInfo 实例
• 构建Docket时通过 select() 方法配置扫描接口
• ApiInfo 主要作用是构建我们接口文档的页面显示的基础信息
• groupName("A") ：表示此Docket实例的名字，也就是接口文档页面右上角选择的实例名，实际开发中我们是多人开发，对应的就是多个Docket实例
• enable(flag) ： enable() 是否启用Swagger，默认是true

运行启动后,输入地址 http://localhost:8080/swagger-ui.html

可以看到Swagger接口界面

3. 实体类配置

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")
    public String name="zhang";
    @ApiModelProperty("用户密码")
    public String password="123";

}

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

@GetMapping(value = "/getUser")
    public User getUser(){
        System.out.println("getUser");
        return new User();
    }

3.常用注解 

我们也可以在接口上添加注释说明，方便我们在接口文档中解释说明接口的信息，例如接口的作用、参数说明等，方便调用者使用.

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上（Controller层的接口方法上）
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO（作用在实体类模块上）
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性（作用在实体类的方法与属性上）
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty（Controller层的接口方法参数上，用来说明参数）