学习目标：

了解Swagger的作用和概念
了解前后端分离
在SpringBoot中集成Swagger

1 谈谈前后端分离

前后端分离开发，需要定义接口，然而写代码的如果同时要去手动维护接口文档，十分繁琐，就有工具出来解决这个痛点，就是Swagger
web开发的历史：

后端主导开发的时代：前端写静态页面，后端把业务逻辑和前端给的页面一起渲染，例如使用模板引擎，jsp
前后端分离时代：
-- 后端：后端分为MVC三层，控制层，业务层，持久层
-- 前端：前端分为MVVM层(不知道我描述的对不对)，视图层，数据层，数据视图层
---- 前端可以伪造后端数据，自己写json字符串，不需要后端就可以把项目跑起来

前后端分离以后，只能过API实现交互，相对独立，松散，耦合低。前后端可以部署在不同的服务器上。

产生的问题：前后端集成联调，前后端人员无法做到“及时协商，及时解决”，可能会导致问题集中爆发
解决方案
-- 指定schema计划提纲，实时更新最新API，降低集成的风险
-- 之前通过指定word计划文档的方式解决
-- 前后端分离以后
---- 前端测试后端接口：postman
---- 后端提供接口，需要实时更新最新的消息及改动

此时Swagger应用而生，解决了这个痛点
Swagger是世界上最流行的API框架之一，提供一个RestFul Api文档在线自动生成工具
可以直接运行，在线测试API接口
支持多种语言：Java，PHP等

官网：https://swagger.io/

在项目中使用Swagger需要SpringBoot(Spring也可以)

Swagger2
UI

2 在SpringBoot项目中集成Swagger

新建一个SpringBoot项目
pom.xml导包

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

编写一个控制器

@Controller
public class IndexController {

    @RequestMapping("/hello")
    @ResponseBody
    public String hello(){
        return "hello";
    }
}

创建配置类，集成Swagger

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

测试访问
测试访问 http://localhost:8080/swagger-ui.html
然后就404了，淦！
找了一下解决方案
因为使用的是3.0版本，重新导入jar

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
</dependency>

然后访问 http://localhost:8080/swagger-ui/index.html

配置Swagger
通过Swagger的bean实例Docket配置
先配置ApiInfo信息

@Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("无名高", "https://wuminggao.cn", "wuminggao594@foxmail.com");

        return new ApiInfo("Swagger接口文档",
                "我是一个描述", "1.0.0",
                "https://wuminggao.cn", contact,
                "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }

可以看到ui界面的变化

可以配置扫描接口的方式

@Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                // basePackage指定要扫描的包
                // any扫描全部
                // none不扫描
                // withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
                // withMethodAnnotation 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.learn.wuminggao.swaggerdemo.controller"))
                //过滤，要扫描的请求路径，此处为扫描/ww下的所有请求路径
                .paths(PathSelectors.ant("/hello/**"))
                .build()
                //是否启用Swagger
                .enable(false);
    }

Swagger在开发环境和测试环境使用，在发布的时候不使用
可以在生产环境的配置文件配置，

springfox:
  documentation:
    swagger-ui:
      enabled: false

可以通过Docket的groupName属性配置group分组信息

主要涉及协同开发的事情，不同group有自己的不同docket实例，可以在ui界面切换查看group

3 接口注释

通过@ApiModel设置类的信息， @ApiModelProperty设置字段的信息
~~注意如果字段是private修饰的，不会在model里面显示~~
此处有误，private属性通过设置get方法就可以显示了

在controller中返回一个model

/**
     * 只要返回值存在一个model，就会在ui看到model
     * @return
     */
    @PostMapping("/user")
    public User helloUser(){
        return new User();
    }

定义实体类

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

}

通过@ApiOperation给控制器方法加注释

@ApiOperation("Index控制器中的hello方法")
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

通过@ApiParam给参数添加注解

@PostMapping("/user")
    public User helloUser(@ApiParam("用户名") String username){
        return new User();
    }

通过@Api给Controller添加注释
@Api(tags = {"Index控制器"}) // tags是对Controller的接口重新分类
public class IndexController

通过这种方式，可以给一些难以理解的属性和接口，添加注释信息
接口文档实时更新
可以在线测试

测试接口

@PostMapping("/user")
    public User helloUser(@ApiParam(value = "用户名", example = "root") @RequestParam("username") String username,
                          @ApiParam(value = "密码", example = "root")@RequestParam("password") String password){
        return new User(username, password);
    }

得到json字符串

Swagger学习笔记

1 谈谈前后端分离

2 在SpringBoot项目中集成Swagger

3 接口注释

Vue学习笔记(二)

小而美博客开发