Swagger的简单介绍

Swagger

学习目标：

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

常用swagger注解：

@EnableSwagger2  //用来在配置类上标注使Swagger服务生效
@Bean //向spring容器中注入一个Docket实例，必须在@Condiguration标注的类中使用
@ApiOperator()  //用来标注接口，如：‘hello接口’解释该接口
@ApiModel（） //用来标注一个Model实体类，并在文档中解释该类
@ApiModelProperty() //用来标注实体类的属性，在文档中解释该属性
@ApiParam（）//用来解释接口入参，一般标注在接口方法的参数上，解释参数

Swagger

前后端分离

Vue + Springboot

后端时代：前端只用管理静态页面；html ==> 模版引擎（thymleaf）、JSP

前后端分离时代：

• 后端：后端控制层，服务层，数据访问层【后端团队】
• 前端：前端控制层，视图层【前端团队】
  • 伪造后端数据，json。已经存在了，不依靠后端，前端也能运行起来
• 前后端如何交互？==>API接口的形式、相对独立、低耦合

产生一个问题：

• 前端人员和后端人员无法做到及时协商，尽早解决，最后导致问题集中爆发！！

解决方案：

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

Swagger的出现

• 号称世界上最流行的Api框架

• Restful Api文档在线的自动生成工具=> Api文档与Api定义同步更新

• 直接运行，可以在线测试接口

• 支持多种语言（java、php…）

  官网：https://swagger.io/

在项目中使用swagger

在项目中使用swagger需要springfox

• swagger2
• ui

1、springboot集成swagger

1、新建一个springboot的项目

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、开启Swagger相关功能配置

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

4.测试swagger运行： localhost:8080/swagger-ui.html

5.配置swagger

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

private ApiInfo apiinfo() {

  Contact contact = new Contact("sofun", "www.shufang.com", "shufangreal@163.com");

  //替换默认配置
  return new ApiInfo("鸟儿配置的接口文档",
                     "即使再笨的鸟也能飞翔",
                     "2.1.0",
                     "https://mp.csdn.net/console/article",
                     contact,
                     "Apache 2.0",
                     "http://www.apache.org/licenses/LICENSE-2.0",
                     new ArrayList()
                    );
}

2、swagger配置扫描接口

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {


    /**
     * 不同的人可以创建并维护自己的Docket分组，每个分组中的models等组件可能是不一样的
     * @return
     */
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("GOOD");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("HELLO");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("WORLD");
    }

    @Bean
    public Docket docket(Environment environment) {

        //获取springboot的不同环境

        Profiles profiles = Profiles.of("test", "dev","pro");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("SOFUN")
                .apiInfo(apiinfo()) //1。配置对应的页面简介信息，版本信息等；
                .enable(flag) //是否开启swagger-ui访问界面：😱 Could not render e, see the console.
                .select() //select()与build()是创建一个Docket的实例
                //any()扫描全部
                //none() 都不扫描
                //withMethodAnnotation() 扫描有注解的方法
                //withClassAnnotation() 扫描有注解的类
                //basePackage(） 扫描指定包下的所有接口
                .apis(RequestHandlerSelectors.basePackage("com.shufang.swagger.controller")) //用来配置API扫描的包，可以是any()、none()、withxxxxx()\basePackage()是生产中最常用的
//                .paths(PathSelectors.ant("/shufang/**")) //用来过滤指定的路径
                .build();//配合select()创建一个Docket实例
    }

    private ApiInfo apiinfo() {

        Contact contact = new Contact("sofun", "www.shufang.com", "shufangreal@163.com");

        //替换默认配置
        return new ApiInfo("鸟儿配置的接口文档",
                "即使再笨的鸟也能飞翔",
                "2.1.0",
                "https://mp.csdn.net/console/article",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }

}

3、配置swagger的Models

配置Model，只需要在接口方法中将指定的pojoJava类实例进行返回，swagger2就会自动将该类添加到Models中

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

    //将原先文档中的Model属性添加上中文注释
    @ApiModelProperty("人员id")
    public String id;
    @ApiModelProperty("人员姓名")
    public String name;
}

@RestController
public class HelloController {

 		@
  	private HashMap<Integer,User> users = new HashMap<>();

    @RequestMapping(value = "/hello")//,method = RequestMethod.GET )
    public String hello() {
        return "hello";
    }

		//这里返回User的实例，所以User就自动被列为一个swagger的Model
    @GetMapping("/user")
    public User user(@ApiParam("userId") int id){
      User user = null;
      
      if(id == 0) return user;
      else return users.get(id);
    }

  	
    @ApiOperation("从前端接收name参数的hello()方法")
    @PostMapping("/hello1")
    public  String hello(@ApiParam("用户名") String name){

        return "hello" + name;
    }
}

4、swagger总结

• 能自动与代码同步生成接口文档
• 支持分组
• swagger可以支持接口在线的测试，前提是springboot服务已经启动