springboot养成计划 （九）Swagger

一 Swagger的作用和概念

前后端分离：
Vue + Springboot
在这里插入代码片后端时代：前端只用管理静态页面；html==>后端。末班引擎JSp=>后端是主力

前后端分离时代：

• 后端：控制层、服务层、数据访问层
• 前端：前端控制层，视图层
• 相对独立，松耦合
• 分开不熟
• 前后端如何交互？ ===>API

前后端集成联调：
首先制定一个计划，实时更新API,降低集成的风险；
早些年：指定word计划文档；
前后端分离：

• 前端测试后端接口：postman
• 后端提供接口，需要实时更新最新的消息及改动

Swagger

• Swagger 是最流行的 API 开发工具，它遵循 OpenAPI
• RestFul Api 文档在线自动生成工具=>API文档与API定义同步更新
• 直接运行，可以在线测试API接口。
• Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。
• Swagger 是一种通用的，和编程语言无关的 API 描述规范。

二 springboot 集成swagger

1） 引入依赖

 <!--swagger依赖-->
 <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>

2）配置

package com.lc.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

@Configuration
@EnableSwagger2 // 开启swagger
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        // 设置只在dev开发中启用Swagger
        Profiles dev = Profiles.of("dev");
        boolean b = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // APi 的默认信息更改
                .enable(b)       // 是否启动Swagger,如果为false则Swagger不能访问（测试环境启动）
                .select()
                // RequestHandlerSelectors 配置要扫描接口的方式
                //指定要扫描的包
                // any()全部扫描
                // withClassAnnotation() 扫描类上的注解 ，参数是一个注解的反射对象
                // withMethodAnnotation() 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.lc.swagger.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("luochao", "https://editor.csdn.net/md?articleId=104498472" , "luochao88@aliyun.com");
        return new ApiInfo(
                "罗超的项目 Swagger API",
                "我爱土狗",
                "v1.0",
                "https://editor.csdn.net/md?articleId=104498472",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

3) 启动项目，查看swagger默认API

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

4）配置扫描接口

.select()           
 // RequestHandlerSelectors 配置要扫描接口的方式
  //指定要扫描的包
  // any()全部扫描
  // withClassAnnotation() 扫描类上的注解 ，参数是一个注解的反射对象
  // withMethodAnnotation() 扫描方法上的注解
  .apis(RequestHandlerSelectors.basePackage("com.lc.swagger.controller"))

5）是否启用swagger

// 设置只在dev开发中启用Swagger
 Profiles dev = Profiles.of("dev");
 boolean b = environment.acceptsProfiles(dev);

 .enable(b)       // 是否启动Swagger,如果为false则Swagger不能访问（测试环境启动）

6）配置API文档的分组

.groupName("罗超")

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

7)实体类配置

@PostMapping("/user")   // 只要接口返回值中存在实体类swagger就会生成实体api
public User user(){
    User user = new User();
    return user;
}

8）添加注解

@Api(tags="hello控制类",value="/hello")
@RestController
@RequestMapping("/hello")
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @ApiOperation("用户添加")
    @PostMapping("/user")   // 只要接口返回值中存在实体类swagger就会生成实体api
    public User user(@ApiParam("用户对象") User user){
        System.out.println(user);
        return user;
    }
}

@ApiModel(value = "User", description = "用户实体类")
@Data
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

总结：
1.我们可以通过Swagger给一些难以理解的类、接口、参数、属性添加注解信息；
2.接口文档可以实时更新；
3.可以在线测试

在正式发布的时候记得禁用swagger