Swagger入门

Swagger简介

前后端分离

Vue+SpringBoot

后端时代：前端只用管理静态页面；html 后端。模板 JSP 后端是主力

 

前后端分离时代

• 后端：后端控制层，服务层，数据访问层

• 前端：前端控制层，视图层

  • 伪造后端数据，json。已经存在了，不需要后端的数据

• 前后端如何交互？ API

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

• 前后端甚至可以部署在不同的服务器上

 

产生一个问题：

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

解决方案：

• 首先指定schema，实时更新最新API，降低集成的风险

• 早些年：制定word计划文档；

• 前后端分离：

  • 前端测试后端接口：postman

  • 后端提供接口，需要实时最新的消息及改动

 

Swagger

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

• RestFul Api 文档在线自动生成工具 Api与API定义同步更新

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

• 只是多种语言（Java，Php。。）

 

 

在项目中使用Swagger，需要springbox；

• swagger2

• ui

 

SpringBoot集成Swagger

1.新建一个SpringBoot-web项目

2.导入相关依赖

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

3.编写helloworld工程

4.配置Swagger Config

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

5.测试运行

http://localhost:8080/swagger-ui.html

peizhiSwagger

Swagger的bean实例Docket；

 package com.zhou.swagger.config;
 ​
 ​
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.service.Contact;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;
 ​
 import java.util.ArrayList;
 ​
 import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;
 ​
 @Configuration
 @EnableSwagger2  //开启Swagger2
 public class SwaggerConfig {
 ​
     //配置了Swagger的Docket实例
     @Bean
     public Docket docket(){
         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
     }
 ​
     //配置Swagger信息=apiInfo
     private ApiInfo apiInfo(){
 ​xiou
         //作者信息
         Contact contact=new Contact("xiou","baidu", "66666");
 ​
         return new ApiInfo(
                 "AntenaAPI",
                 "kou Api Documentation",
                 "1.0",
                 "urn:tos",
                 contact,
                 "Apache 2.0",
                 "http://www.apache.org/licenses/LICENSE-2.0",
                 new ArrayList());
 ​
     }
 }

Swagger配置扫描接口

Docket.select()

    public Docket docket(){
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .select()
                  //requestHandlerSelectors，配置要扫描接口的方式
                 //basePackage，指定要扫描的包
                 //any() 扫描全部
                 //none() 不扫描
                 //withClassAnnotation 扫描类上的注解
                 //withMethodAnnotation 扫描方法上的注解
                 .apis(RequestHandlerSelectors.basePackage("com.zhou.swagger.controller"))
                 //选择路径,过滤
                 .paths(PathSelectors.ant("/zhou/**"))
                 .build();
     }

配置是否启动

  //配置了Swagger的Docket实例
     //enable是否启动Swagger，false则swagger不能在浏览器中访问
     @Bean
     public Docket docket(){
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .enable(false)
                 .select()
                  //requestHandlerSelectors，配置要扫描接口的方式
                 //basePackage，指定要扫描的包
                 //any() 扫描全部
                 //none() 不扫描
                 //withClassAnnotation 扫描类上的注解
                 //withMethodAnnotation 扫描方法上的注解
                 .apis(RequestHandlerSelectors.basePackage("com.zhou.swagger.controller"))
                 //选择路径,过滤
                 .paths(PathSelectors.ant("/zhou/**"))
                 .build();
     }

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

  public Docket docket(Environment environment){
         //设置要显示的swagger环境
         Profiles profiles= Profiles.of("dev", "test");
         //获取项目的环境,判断是否处于自己设定的环境中
         boolean flag=environment.acceptsProfiles(profiles);
 ​
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .enable(flag)

配置API分组

 .groupName("kokokp")

如何配置多个组；多个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");
     }

 

实体类配置

@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    //只要我们的接口中，返回值中存在实体类，它就会被扫描到Swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
}

//@Api(注释)
@ApiModel("用户实体类")
public class User {

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

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

总结：

1. 我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息

2. 接口文档实时更新

3. 可以在线测试

 

Swagger是一个优秀的工具

注意点

在正式发布的时候，关闭Swagger！！！出于安全考虑，而且节省运行内存。