侧边栏壁纸
博主头像
coydone博主等级

记录学习,分享生活的个人站点

  • 累计撰写 306 篇文章
  • 累计创建 51 个标签
  • 累计收到 0 条评论

目 录CONTENT

文章目录

SpringBoot集成Swagger

coydone
2022-04-14 / 0 评论 / 0 点赞 / 318 阅读 / 6,974 字 / 正在检测是否收录...
温馨提示:
本文最后更新于 2022-07-03,若内容或图片失效,请留言反馈。部分素材来自网络,若不小心影响到您的利益,请联系我们删除。

Swagger产生背景

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架,而且swagger可以完全模拟http请求,入参出参和实际情况差别几乎为零。

没有API文档工具之前,大家都是手写API文档的(维护起来相当困难),在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。但是能称之为“框架”的,估计也只有Swagger了。

Swagger介绍

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

作用:接口的文档在线自动生成;功能测试。

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

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

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

  • 支持多种语言(如java、php等)

官网:https://swagger.io/

在项目中使用Swagger需要springfox;

SpringBoot集成Swagger

1、新建一个SpringBoot的Web项目

2、导入相关依赖

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

3、编写一个Hello工程

package com.coydone.swagger.controller;
//http://localhost:8080/hello
@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

4、配置Swagger,使用Config配置类

package com.coydone.swagger.config;

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

5、访问http://localhost:8080/swagger-ui.html。

配置Swagger

Swagger的bean实例Docket源码

public class Docket implements DocumentationPlugin {
    // 默认的组,对应页面中的default
    public static final String DEFAULT_GROUP_NAME = "default";
    public Docket(DocumentationType documentationType) {
    	this.apiInfo = ApiInfo.DEFAULT;
        this.groupName = "default";
        this.enabled = true;
        this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
        this.applyDefaultResponseMessages = true;
        this.host = "";
        this.pathMapping = Optional.absent();
        this.apiSelector = ApiSelector.DEFAULT;
        this.enableUrlTemplating = false;
        this.vendorExtensions = Lists.newArrayList();
        this.documentationType = documentationType;
    }
}
// api信息
public class ApiInfo {
    public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
    public static final ApiInfo DEFAULT;
    private final String version;// 版本 1.0 
    private final String title;// 标题  Api Documentation
    private final String description;// 描述 Api Documentation 
    private final String termsOfServiceUrl;// 服务条款路径 urn:tos
    private final String license;// 许可证 Apache 2.0
    private final String licenseUrl;// 地址:http://www.apache.org/licenses/LICENSE-2.0
    private final Contact contact;// DEFAULT_CONTACT
    private final List<VendorExtension> vendorExtensions;// new ArrayList()
	......
    static {
        DEFAULT = 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());
    }
}
public class DocumentationType extends SimplePluginMetadata {
    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
}

我们只需在自己的配置类中按照它给我们提供的样式自定义。

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

@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    //配置swagger信息  apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("coydone", "https://www.coydone.com/", "coydone@163.com");
        return new ApiInfo("coydone的SwaggerAPI文档",
                "学习java,学习编程",
                "1.0",
                "https://www.coydone.com/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

Swagger配置扫描接口

Docket.select()

//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors:配置要扫描接口的方式
            //basePackage():指定要扫描的包   any():扫描全部  none():不扫描
            //withClassAnnotation(RestController.class):扫描类上的注解,参数是一个注解的反射对象
            //withMethodAnnotation(GetMapping.class):扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.coydone.swagger.controller"))
            //paths():过滤什么路径
            .paths(PathSelectors.ant("/coydone/**"))
            //工厂模式
            .build();
}

配置是否启动Swagger

public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //默认为true 启动Swagger,如果为false,则在浏览器中无法访问Swagger
            .enable(false)
            .select()
          .apis(RequestHandlerSelectors.basePackage("com.coydone.swagger.controller"))
            .build();
}

我只希望我的Swagger在开发环境中使用,在生产环境中不使用?

  • 判断是不是生产环境:flag=false

  • 注入enable(flag)

演示:在application.properties中

spring.profiles.active=dev

新建application-dev.properties →server.port=8081

新建application-pro.properties →server.port=8082

修改SwaggerConfig配置类

@Bean
public Docket docket(Environment environment){
    //设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");
    //判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)
            .select()
          .apis(RequestHandlerSelectors.basePackage("com.coydone.swagger.controller"))
            //.paths(PathSelectors.ant("/coydone/**"))
            .build();
}

http://localhost:8081/swagger-ui.html:开发环境可以访问。

http://localhost:8082/swagger-ui.html:生产环境不能访问。

配置API文档的分组

.groupName("A")

设置多个分组:多个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");
}

API注释

package com.coydone.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//给生成的文档加注释
//@Api(value="注释")
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}
package com.coydone.swagger.controller;

@Api(tags = "hello 控制类")
@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
    //只要我们的接口中,返回值中存在实体类,它就会被扫描到Swagger中
    @ApiOperation("post测试类")
    @PostMapping("/user")
    public User user(){
        return new User();
    }
    //Operation接口,放在方法上
    @ApiOperation("get测试类")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }
}

总结:

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

2、接口文档实时更新。

3、可以在线测试。

【注意点】在项目正式发布的时候,关闭Swagger。出于安全考虑。而且节省运行的内存。

参考:https://www.jianshu.com/p/a0caf58b3653。

0

评论区