前后端分离缺陷

了解Swagger之前,需要先知道什么是前后端分离

• 现在的时代
  • SpringBoot + VUE
• 以前的时代
  • SSM + JSP模板引擎====>后端程序员
• 前后端分离时代
  • 通过相关的API接口进行交互
  • 前后端相对独立,松耦合
  • 前后端可以分别部署在不同的服务器上
  • 伪造后端交互数据,json数据已经存在,不需要后端传入json数据了,前端工程已经可以运行
  • 后端:后端控制层 + 服务层 + 数据访问层
  • 前端:前端控制层 + 视图层
  • 前后端如何交互?
• 但这样会产生新问题
  • 前后端集成联调,前端和后端开发人员无法做到及时协商,尽早解决问题,就会导致项目延期
• 解决方案:
  • 前端测试后端:postMan
  • 后端提供接口,需要实时更新最新的消息和改动
  • 首先指定schema[计划大纲],团队实时更新最新的API,可以降低集成的风险;
  • 早些年:指定world计划文档
  • 前后端分离:

Swagger简介

Swagger官网

• 号称世界上最流行的API框架
• RestFul API文档在线生成工具--->>>==API文档与API同步更新==
• 可以直接运行,可以在线测试API接口
• 支持多种语言:(Java,PHP......)

使用SpringBoot集成Swagger

• 创建SpringBoot-Web项目,导入相关依赖

注意事项:

• 在项目中使用Swagger需要SpringBox
• swagger2
• swaggerui

        <dependency>            <groupId>io.springfoxgroupId>            <artifactId>springfox-swagger2artifactId>            <version>2.9.2version>        dependency>

        <dependency>            <groupId>io.springfoxgroupId>            <artifactId>springfox-swagger-uiartifactId>            <version>2.9.2version>        dependency>

• 创建hello程序

扩展,一个hello程序有两个请求,一个是SpringBoot项目默认的/error

@RestControllerpublic class HelloController {    /**     * 测试Controller     *     * @return     */    @GetMapping("/hello")    public String hello() {        return "你好呀!!!Swagger";    }}

• 配置Swagger,新建SwaggerConfig

@Configuration // 标识配置类@EnableSwagger2 // 开启Swaggerpublic class SwaggerConfig {

}

• 测试运行

唯一地址:http://localhost:8080/swagger-ui.html

配置Swagger信息

• 修改SwaagerConfig

package com.mobai.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;

/** * Software：IntelliJ IDEA 2020.1 x64 * Author: MoBai·杰 * Date: 2020/6/11 13:33 * ClassName:SwaggerConfig * 类描述：Swagger配置类 */@Configuration // 标识配置类@EnableSwagger2 // 开启Swaggerpublic class SwaggerConfig {

    /**     * 配置了Swagger的Docket的Bean实例     *     * @return     */    @Bean    public Docket docket() {        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());    }

    /**     * 配置Swagger信息     *     * @return     */    private ApiInfo apiInfo() {        // 配置作者信息        Contact contact = new Contact("墨白",                "https://www.mobaijun.com",                "mobaijun8@163.com");        // 配置API文档标题        return new ApiInfo("框架师Api",                // API文档描述                "Api Documentation",                // API版本号                "1.0",                // 配置URL(公司官网/blog地址)                "https://www.mobaijun.com",                // 作者信息                contact,                // 以下内容默认即可                "Apache 2.0",                "http://www.apache.org/licenses/LICENSE-2.0",                new ArrayList());    }

}

Swagger配置扫描接口

Docket.select();

• 在SawggerConfig配置类完善配置扫描接口的参数

 /**  * 配置了Swagger的Docket的Bean实例  *  * @return  */ @Bean public Docket docket() {     return new Docket(DocumentationType.SWAGGER_2)             .apiInfo(apiInfo())             // 配置扫描接口             .select()             /*              *RequestHandlerSelectors,配置要扫描接口的方式              * 参数说明:              * basePackage:基于包扫描              * class:基于类扫描              * any():扫描全部              * none():全部都不扫描              * withMethodAnnotation:通过方法的注解扫描              * // withMethodAnnotation(GetMapping.class))              * withClassAnnotation:通过类的注解扫描              */             .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))             // .paths()过滤,不扫描哪些接口             .paths(PathSelectors.any())             .build(); }

• 配置Swagger启动

/** * 配置了Swagger的Docket的Bean实例 * * @return */@Beanpublic Docket docket() {    return new Docket(DocumentationType.SWAGGER_2)            .apiInfo(apiInfo())            // 配置Swagger是否启动,默认:true            .enable(false)            // 配置扫描接口            .select()            .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))            .paths(PathSelectors.any())            .build();}

小测试:如果有一个需求,需要你判断在生成环境中使用,在发布的时候不使用

• 开发思路
  • 先判断.enable()是不是等于false
  • 注入Enable(flag)

• 实现,添加application-dev.properties生产环境配置和application-pro.properties发布环境配置

• 默认application.properties环境配置添加

# 开启profiles.active监听,dev测试环境,pro发布环境spring.profiles.active=dev

• 生产环境修改端口号

server.port=8081

• 发布环境修改端口号

server.port=8082

• SwaggerConfig配置类判断当前环境

/** * 配置了Swagger的Docket的Bean实例 * * @return */@Beanpublic Docket docket(Environment environment) {    // 设置要显示的Swagger环境    Profiles profiles = Profiles.of("dev", "test");    // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)            .apiInfo(apiInfo())            // 监听自己设置的环境            .enable(flag)            // 配置扫描接口            .select()            .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))            .paths(PathSelectors.any())            .build();}

配置API文档的分组

• 配置多个组,添加.groupName()

   /**     * 配置了Swagger的Docket的Bean实例     *     * @return     */    @Bean    public Docket docket(Environment environment) {        // 设置要显示的Swagger环境        Profiles profiles = Profiles.of("dev", "test");        // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                // 配置分组                .groupName("墨白小组")                // 监听自己设置的环境                .enable(flag)                // 配置扫描接口                .select()                .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))                .paths(PathSelectors.any())                .build();}

• 效果

• 配置多个组

@Configuration // 标识配置类@EnableSwagger2 // 开启Swaggerpublic class SwaggerConfig {

    /**     * 添加A组     * 每个组各司其职     *     * @return     */    @Bean    public Docket docket1() {        return new Docket(DocumentationType.SWAGGER_2)                .groupName("A");    }

    /**     * 添加B组     *     * @return     */    @Bean    public Docket docket2() {        return new Docket(DocumentationType.SWAGGER_2)                .groupName("B");    }

    /**     * 添加C组     *     * @return     */    @Bean    public Docket docket3() {        return new Docket(DocumentationType.SWAGGER_2)                .groupName("C");    }

    /**     * 配置了Swagger的Docket的Bean实例     *     * @return     */    @Bean    public Docket docket(Environment environment) {        // 设置要显示的Swagger环境        Profiles profiles = Profiles.of("dev", "test");        // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                // 配置分组                .groupName("墨白小组")                // 监听自己设置的环境                .enable(flag)                // 配置扫描接口                .select()                .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))                .paths(PathSelectors.any())                .build();    }

• 效果

• 实体类配置

@ApiModel("用户实体类") // 添加注释public class User {    // 添加注释    @ApiModelProperty("年龄")    private Integer age;

    @ApiModelProperty("姓名")    private String name;

    @ApiModelProperty("账号")    private String username;

    @ApiModelProperty("密码")    private String password;

    public Integer getAge() {        return age;    }

    public void setAge(Integer age) {        this.age = age;    }

    public String getName() {        return name;    }

    public void setName(String name) {        this.name = name;    }

    public String getUsername() {        return username;    }

    public void setUsername(String username) {        this.username = username;    }

    public String getPassword() {        return password;    }

    public void setPassword(String password) {        this.password = password;    }}

• 效果

• Swagger常用注解

  • @ApiModel("注释"):实体类添加注释
  • @ApiModelProperty("注释"):给实体类属性添加注释
  • @ApiOperation("注释")给接口(Controller)方法添加注释,放在方法上
  • @ApiParam("")给方法的参数添加注释
  • @Api("")给类添加注释

• controller

package com.mobai.swagger.controller;

import com.mobai.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.RestController;

/** * Software：IntelliJ IDEA 2020.1 x64 * Author: MoBai·杰 * Date: 2020/6/11 13:25 * ClassName:HelloController * 类描述： 测试类 */@ApiOperation("")@RestControllerpublic class HelloController {    /**     * 测试Controller     *     * @return     */    @GetMapping("/hello")    public String hello() {        return "你好呀!!!Swagger";    }

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

    @ApiOperation("Post测试类")    @PostMapping(value = "/post")    public User post(@ApiParam("用户对象") User user) {        return user;    }}

• 总结

  • 添加@Configuration注解,标识配置类
  • 添加@EnableSwagger2注解开启Swagger
  • Swagger2
  • Swagger-ui
  • 创建SpringBoot项目,导入Swagger依赖
  • 创建Swagger配置类
  • 配置Swagger的Docket的Bean实例
  • 配置Swagger信息

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

• 接口文档实时更新

• 可以在线测试

• Swagger是一个优秀的工具,几乎所有的大公司都在用

• 需要注意:正式发布的时候,关闭swagger!!!出于安全考虑,而且节省运行内存!

感谢阅读,如果有帮助到你,请转发,点击再看,这是我分享的动力,感谢

• IntelliJ IDEA 插件,用了上头的那种

• 面8-15K可能会遇到的面试题

• 精选SpringCloud微服务实战项目[视频,源码]

• 如何利用码云搭建一个自己的图床?