Swagger学习

Swagger

学习目标：

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

Swagger简介

前后端分离
Vue+SpringBoot
后端时代：前端只用管理静态页面；html==>后端。模板引擎 Jsp=>后端是主力

前后端分离时代：

• 后端：后端控制层，服务层，数据访问层【后端团队】

• 前端：前端控制层，视图层【前端团队】
  。伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来

• 前后端如何交互？===>API

• 前后端相对独立，松耦合；

• 前后端设置口语部署在不同的服务器上；

产生一个问题：

• 前后端集成联调，前端人员和后端人员无法做到 “即使协调，尽早解决”，最终导致问题集中爆发；

解决方案：

• 首先指定schema【计划的提纲】，实时更新最新API，降低集成的风险；
• 早些年：制定word计划文档；
• 前后端分离：1。前端测试后端接口：postman 2。后端提供接口，需要实时更新最新的消息及改动！

Swagger

• 号称世界上最流行的Api框架；
• RestFul Api 文档在线自动生成工具=>Api文档与API定义同步更新
• 直接运行，可以在线测试API接口；
• 支持多种语言：（Java PHP…）

官网：https://swagger.io/

在项目中使用Swagger需要 springbox；

• swagger2
• ui
  下包：https://mvnrepository.com/search?q=springfox-swag
  

springboot集成swagger

1.新建一个springboot =web项目
2.导入相关依赖

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

3.编写一个hello工程
4.配置Swagger ==>Config

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

5.测试运行

配置Swagger

Swagger的bean实例 Docket；

 //配置了Swagger的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("陈雨", "urn:tos", "731714510@qq.com");
        return   new ApiInfo("陈雨的学习路程",
                "加油加油",
                "s1.0",
                "urn:tos",
                contact, "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());

    }

Swagger配置扫描接口

Docket.select()

 //配置了Swagger的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors,配置要扫描的接口方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解,参数是一个注解的反射现象
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.yu.swagger.controller"))
                //.paths. 过滤什么路径
                .paths(PathSelectors.ant("/yu/**"))
                .build();
    }

配置是否启动Swagger

  @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//enable 是否启用Swagger，如果为false，则Swagger不能在浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yu.swagger.controller"))
                //.paths(PathSelectors.ant("/yu/**"))
                .build();
    }

我只希望我的Swagger在生产环境中使用，在发布的时候不使用?

• 判断是不是生产环境 flag=false
• 注入enable（flag）

配置API文档的分组

如何配置多个分组；多个Docket实例即可

 @Bean
    public  Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public  Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public  Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

实体类配置

package com.yu.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api(注释)
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

controller

package com.yu.swagger.controller;

import com.yu.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
//@ApiOperation("hello控制类")//接口
@RestController
public class HelloController {
    ///error 都会存在这个默认请求
    @GetMapping (value = "/hello")
    public  String hello(){
        return "hello";
    }
//只要我们的接口中，返回值存在实体类，他就会被扫描到Swagger中
    @PostMapping(value = "/user")
        public User user(){
        return new User();
    }
    //Operation 接口,不是反正类上的，是方法
    @ApiOperation("hello控制类")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;

    }
    @ApiOperation("post测试")
    @PostMapping(value = "/postt")
    public User postt(@ApiParam("用户名") User user){
        return user;

    }

}

总结;
1.我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
2.接口文档实时更新
3.可以在线测试
Swagger是一个优秀的工具
正式发布的时候，关闭Swagger！！！ 出于安全考虑，而且节约内存。