（三） spring boot 之使用Swagger配置详解

最新推荐文章于 2024-07-27 13:06:23 发布

Geek-Banana

最新推荐文章于 2024-07-27 13:06:23 发布

阅读量1.9k

点赞数 2

分类专栏： SpringBoot系列博客文章标签： springboot swagger swagger配置 swagger详解 springboot配置swagger

本文链接：https://blog.csdn.net/qq1515312832/article/details/103212461

版权

SpringBoot系列博客专栏收录该内容

10 篇文章 2 订阅

订阅专栏

为什么我会要专门在 springboot 系列中专门写一篇来介绍 swagger 呢，主要是因为我在日常的工作中真的是受够了这些不规范的接口，每次看自己负责的项目中的接口，心里都会默念一万句MMP。

所以我要写一篇博客来介绍 swagger 的配置详细解释，博文中有写的不对的地方希望大家指出，如果有什么好的想法也可以告诉我再加上。

还是要说一下，这些注解没有可以吗？
完全可以，但是为了你自己看的更加清楚，也为了别人看的更加清楚，当然更为了你自己的人身安全，还是建议写上。

springboot 配置 swagger 页面

（一） SpringBoot 项目初始化 + 配置swagger页面

swagger 页面的标题配置

页面的可配置项有很多，包括标题、版本、姓名、个人网站、email等等

值得注意的是一定要记得添加的三个注解
@Configuration 将swagger页面配置到项目的加载中
@EnableSwagger2 开启swagger页面的使用
@Bean 将swagger页面的信息加载到Bean工厂中

package com.banana.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    // 配置swagger页面的头部
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Banana's SpringBoot APIs")            // 配置页面的标题
                .description("这里是Banana的swagger页面")      // 配置页面的简介
                .contact(new Contact("Banana",          // 配置页面联系，包括姓名，url，email
                        "https://blog.csdn.net/qq1515312832",
                        "dlt1997@outlook.com"))
                .version("1.0")                               // 配置页面的版本
                .build();
    }
}

这里配置好之后我们的页面上就会显示出来我们所需要的信息，如下
在这里插入图片描述

对 Controller 添加注解

对 Controller 类添加注解

首先，我们可以对整个 Controller 添加注解，对当前的 Controller 做一个注释
在这里插入图片描述
对应的页面则是这样的，对应的Controller会显示为我们所需要的文字

对 Controller 类中的接口添加注解

没有参数的接口

在这里插入图片描述
使用@ApiOperation注解来对当前的接口做一个注释，value为当前接口的简述，notes为更为详细的叙述

有参数，但是没有在 uri 里的接口

在这里插入图片描述
这类的接口是有参数的，它的参数会自动拼接到url中传入进来，后端可以接收到，我们访问的url就会如下这样，userName就会拼接到url的后方

http://localhost:8088/user/getUserListByName?userName=1

我们在swagger页面配置以后，参数就会显示出来
name是参数的名称
value是参数的含义
dataType是参数的类型
required是参数是否必须
配置好就会显示如下界面：
在这里插入图片描述

uri中含有参数的接口

在这里插入图片描述
这个时候就会使用@PathVariable注解来标识参数，这个注解的适用场景是这个参数一定要在上面的uri中含有才可以，这样才能识别到参数，否则这个接口在运行时就会直接报错

参数是实体的接口

有特殊的情况，我们的参数中有实体，也可以当作json，所我们需要保证在swagger页面中比较好用，我们的实体都是一样的，但是我们把这些实体的模板自动化的加载出来就可以不用再去手动输入了。

所以我们就需要加@ApiParam的注解，来保证可以自动化的添加出来需要传入的实体。

@RequestBody注解的含义是要从请求体中获取到当前的参数来进行赋值。
在这里插入图片描述
在swagger页面我们可以获得的配置就会变成这样，我们的参数中就会获得到我们需要的实体的参数，不需要再去重新写了，同时我们也可以保留我们所需要的，删去多余的，方便高效

对实体添加swagger注解

对于实体，我们可以添加@ApiModeal注解，来标识此实体是用于何处

对于实体中的参数，我们也可以标识出属性含义，使用@ApiModelProperty

package com.banana.demo.entity;

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

@Data
@ApiModel(value = "User:用户表")
public class User {
    @ApiModelProperty("用户 id")
    private String id;
    @ApiModelProperty("用户 姓名")
    private String user_name;
    @ApiModelProperty("用户 密码")
    private String user_password;

    public User() {
    }

    public User(String id, String user_name, String user_password) {
        this.id = id;
        this.user_name = user_name;
        this.user_password = user_password;
    }
}