Swagger的配置与使用

最新推荐文章于 2024-09-25 14:27:09 发布

秋田狗子

最新推荐文章于 2024-09-25 14:27:09 发布

阅读量909

点赞数

分类专栏： springboot 文章标签： swagger springboot spring swagger2

本文链接：https://blog.csdn.net/KJ_Study/article/details/109321368

版权

springboot 专栏收录该内容

4 篇文章 0 订阅

订阅专栏

问题：前后端分离时代的到来

前端需要测试后端数据
后端提供接口，实时更新接口的改动

一、Swagger简介

号称世界上最流行的api框架
Restful api文档在线自动生成工具–>api文档与api定义同步更新
直接运行，可以在线测试api接口
支持多种语言(java、php)

官网：https://swagger.io/

在项目中使用swagger需要springfox jar包

swagger2
swagger ui

二、springboot集成swagger

新建springboot项目

导入jar包

<!--swaggerjar包-->
<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>

编写一个helloworld

package com.kj.controller;

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

@RestController
public class SwaggerController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

配置swagger

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

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

}

启动类加上@EnableSwagger2注解（遇到Unable to infer base url.bug时加入，可以解决）

package com.kj;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }

}

启动运行

访问localhost/swagger-ui.html。没有配置port的是这个地址localhost:8080/swagger-ui.html

swagger-ui.html所在文件

三、配置swagger

1、配置ApiInfo

swagger需要一个docket实例

可以看到docket的构造函数，需要一个DocumentationType

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;
}

而DocumentationType有三个默认的值

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");
    
......
    
}

所以我们可以这样向容器中创建一个docket

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2);
}

此时改配置信息，调用docket的函数即可。

比如修改swagger的api信息，我们需要更改ApiInfo
在这里插入图片描述

2、配置扫描接口

有一个方法Docket.select()

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .build();
}

只能build两个方法apis与paths

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-1J666Gso-1603805413097)(D:\java\myNote\image\812217.png)]$

配置扫描目标

有扫描全部any，一个都不扫描none，基于包扫描basePackage，通过方法注解扫描（扫描有这个注解的方法，可以自己加入GetMapper.class的参数），通过类注解扫描

用的多的还是basePackage

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-AB4tC2n6-1603805413098)(D:\java\myNote\image\016579.png)]$

我们指定一个扫描包

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
        .build();
}

结果

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-ofGBSf7x-1603805413099)(D:\java\myNote\image\7201240619.png)]$

3、过滤路径

扫描带有/kj/ url的api，我们只有一个/hello请求，所以不会有任何api

@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.kj.controller"))
    .paths(PathSelectors.ant("/kj/**"))
    .build();
}

4、配置是否启用swagger

将docket的enabled属性改为false即可

//docket的部分源码
public Docket(DocumentationType documentationType) {
    this.apiInfo = ApiInfo.DEFAULT;
    this.groupName = "default";
    this.enabled = true; //是否使用swagger
    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;
}

public Docket enable(boolean externallyConfiguredFlag) {
    this.enabled = externallyConfiguredFlag;
    return this;
}

所以我们enable一下

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
            .build()
            .enable(false);
}

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-jWng4qK8-1603805413100)(D:\java\myNote\image\535525.png)]$

实际使用：我们通过外部的环境来判断是否调用swagger

@Bean
public Docket docket(Environment environment){
    //设置显示要调用swagger的环境，可以有多个值
    Profiles profiles = Profiles.of("dev");
    //判断当前的环境与指定的是否一样
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kj.controller")) //RequestHandlerSelectors配置扫描接口的方式
            .build()
            .enable(flag);
}

我们有多个配置文件，一个用于开发，一个用于部署

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-e4mB3D9B-1603805413101)(D:\java\myNote\image\319216.png)]$

5、配置api文档的分组

主要的是groupName

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;
}

@Bean
public Docket docket(Environment environment){
    Profiles profiles = Profiles.of("dev");
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.kj.controller"))
            .build()
            .enable(flag)
            .groupName("KJ");
}

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-bMU5MBRm-1603805413102)(D:\java\myNote\image\920.png)]$

我们可以看到一个docket一个分组。要想要多个我们再创建几个docket即可。

注意组名不能相同，如果相同spring会报bug并结束进程

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

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

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())
        .groupName("C");
}

不同后端开发人员选择自己的组，就可以只看到自己的api

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-foJEggcE-1603805413103)(D:\java\myNote\image\3072.png)]$

6、实体类配置

只要返回值中存在，就会被swagger扫描

编写一个pojo

package com.kj.pojo;

public class User {
    private String username;
    private String password;
}

编写一个方法

@RestController
public class SwaggerController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping("/user")
    public User user(){
        return new User();
    }
}

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-9RDP8v0R-1603805413104)(D:\java\myNote\image\725082.png)]$

我们也可以在实体类加上注注释（在显示时，只显示注解配置的内容），显不显示与这个注解无关

package com.kj.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    private String password;
}

可以看到私有方法是看不到的

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Nxr5Vt9m-1603805413105)(D:\java\myNote\image\029103.png)]$

同样我们也可以给方法加注释，或者给参数加注释

@RestController
public class SwaggerController {

    @ApiOperation("哈喽方法")
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping("/user")
    public User user(){
        return new User();
    }
    
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String name){
        return "hello";
    }
}