Swagger

掌握：

  • Swagger的作用和概念

  • 前后端分离概念

  • 在Springboot中集成Swagger

前后端分离

当前：vue+springboot

后端时代：前端只管理静态页面。写好后交给（html页面）交给后端处理。当时用到的模板引擎JSP，需要放进服务器跑，后端是主力。

前后端分离时代：

  • 后端：后端服务层，服务层，数据访问层 【后端团队】
  • 前端：前端控制层，视图层 【前端团队】
    • 伪造后端数据，json数据。不需要后端团队程序也能跑起来
  • 前后端交互 ===> API
  • 前后端相对独立，松耦合
  • 前后端可以部署在不同服务器

产生问题：

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

解决办法：

  • 首先制定schema(计划/提纲/纲要)。实时更新最新API，降低集成风险
  • 早些年，制定work计划文档。
  • 前后端分离：
    • 前端测试后端接口：postman
    • 后端提供接口，需要实时更新最新消息及改动。

Swagger简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

  • 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
  • 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

查看官网

项目中使用Swagger需要springboot

  • swagger2
  • ui

spring boot中集成Swagger

1、新建springboot项目

2、导入相关依赖

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

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

3、编写hello工程

package com.luyidog.swaggerdemo.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String hello() {
        return "hello";
    }
}

4、配置SwaggerConfig

package com.luyidog.swaggerdemo.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //加入到配置类 springboot声明配置类
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {

}

5、测试访问页面

​ 测试地址/swagger-ui.html，出现swagger接口文档页面

6、配置Swagger的bean实例Docket

使用提供的构造方法接管默认的方法

Swagger的bean实例Docket

package com.luyidog.swaggerdemo.config;

import io.swagger.annotations.Api;
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;

@EnableSwagger2  //开启Swagger2
@Configuration //加入到配置类 springboot声明配置类
public class SwaggerConfig {

    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
        //new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT,
        // "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }

    //配置Swagger信息 => apiInfo()
    private ApiInfo apiInfo() {
        //作者信息
        final Contact contact = new Contact("Naughty", "https://blog.csdn.net/g200000", "luyidog@aliyun.com");

        return new ApiInfo("Naughty的SwaggerDemoAPI文档",
                "年轻就应该投资大脑",
                "v1.0",
                "https://blog.csdn.net/g200000",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

7、配置扫描接口及开关

Docket.select()

源码中有具体详细的实现过程

 //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	//.enable(flag)
                .select()
                //RequestHandlerSelectors：配置要扫描接口的方式
                //basePackage：指定要扫描的包
                //any() ：扫描全部
                //none()：都不扫描
                //withClassAnnotation(RestController.class)：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation(GetMapping.class)：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.luyidog.swaggerdemo.controller"))
                //paths()过滤什么路径
                .paths(PathSelectors.ant("/luyidog/**"))
                .build();//build新建某个东西=>扫描接口

    }

Q:在生产环境中使用swagger，在发布的时候不使用。

A:获取当前项目生产环境，判断是否为设定的的环境，否则返回false

public Docket docket(Environment environment) {
        //Q:在生产环境中使用swagger，在发布的时候不使用。
        //获取当前项目的生产环境
        Profiles profiles = Profiles.of("dev","test");//设置要显示的swagger环境
        //通过environment.acceptsProfiles()判断是否处在自己设定的环境
        final boolean flag = environment.acceptsProfiles(profiles);//生产、测试环境返回true

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.luyidog.swaggerdemo.controller"))
                //.paths(PathSelectors.ant("/luyidog/**"))
                .build();//build新建某个东西=>扫描接口

    }

8、分组和接口注释及小结

.groupName("Naughty")//配置默认分组

协作开发使用，设置不同分组扫描自己的接口，用于说明

配置多个分组：设置多个Docket即可

@Bean
public Docket docket(Environment environment) {
    //Q:在生产环境中使用swagger，在发布的时候不使用。
    //获取当前项目的生产环境
    //设置要显示的swagger环境
    Profiles profiles = Profiles.of("dev", "test");
    //通过environment.acceptsProfiles()判断是否处在自己设定的环境
    final boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("Naughty")//配置默认分组
        .enable(flag)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.luyidog.swaggerdemo.controller"))
        //.paths(PathSelectors.ant("/luyidog/**"))
        .build();//build新建某个东西=>扫描接口

}

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

给属性或接口写注释信息：

package com.luyidog.swaggerdemo.controller;
@RestController //声明所有Controller返回json格式，可以直接编写返回接口
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello(@ApiParam("用户名") String username) {
        return "hello" + username;
    }

    @ApiOperation("Hello控制类")//放到接口方法上，接口注释文档
    @PostMapping(value = "/user")
    public User user() {
        return new User();
    }
}

/

package com.luyidog.swaggerdemo.pojo;

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

总结：

我们可以通过swagger给一些比较难理解的属性或接口写注释信息，并且接口文档实时更新，支持在线测试

注意：

在正式发布的时候关闭Swagger

# 前端 # spring boot # 后端
Logo
Eolink 开发者社区

权威｜前沿｜技术｜干货｜国内首个API全生命周期开发者社区

更多推荐

cover

AI 消灭软件工程师？| 新程序员

avatar Eolink 开发者社区
cover

GPT 时代的程序员生存之道 | 新程序员

avatar Eolink 开发者社区
cover

Eolink 2023年度回顾，邀您见证成长！

avatar Eolink 开发者社区