Swagger零基础教学，看这篇就够啦！

一、简介

Swagger的官网地址 ​​​​​​https://swagger.io/

swagger优势：

• 号称世界上最流行的api框架
• RestFul Api文档在线自动生成工具=》Api文档与API定义同步更新
• 直接运行，可以在线测试API接口
• 支持多种语言

使用springboot结合swagger

二、SpringBoot集成Swagger

1、创建springboot-web项目

说到springboot那肯定是要创建一个springboot项目啦

创建完毕之后导入swagger的两个依赖

2.导入相关依赖

导入swagger和ui的依赖

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

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

导入完依赖记得刷新一下哦~

3、编写一个hello工程

用最简单的代码来测试这个swagger是否成功

写一个Controller控制层，这边要注意测试App的类和controller包应该在同级目录

package org.example.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

4、写配置类

==》配置swagger ==》Config

package com.cykj.swagger2.demos.config;

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

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

5、测试

http://localhost:8080/swagger-ui.html

访问这个就可以得到swagger测试了（我的端口号8080，实际的看自己的端口号）

这样子就是访问成功

然后我们来解释一下这些模块，大概分为四个模块

到这边我们就对swagger有个基本的了解啦，往下我们来对应这四个模块进行一一测试

三、配置swagger信息

swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息在apiInfo中

我们在配置类里面先new Docket一下，然后我们再点击进去看看源码

package com.cykj.swagger2.demos.config;

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

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        //还未写完整
    }
}

可以再点击ApiInfo点击进去查看具体有什么信息

这样子我们通过读懂源码也可进行直接配置，不用去查资料什么的

所以总的配置代码如下

package org.example.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("小赖", "https://blog.csdn.net/cfjbcg?spm=1011.2124.3001.5343", "111");
        return new ApiInfo("小赖的SwaggerAPI",
                           "美好的一天，有薯片~",
                           "v1.0",
                           "https://blog.csdn.net/cfjbcg?spm=1011.2124.3001.5343",
                           contact,
                           "Apache 2.0",
                           "http://www.apache.org/licenses/LICENSE-2.0",
                           new ArrayList());
    }
}

重启服务器，刷新页面，就可以看到swagger的基本信息被修改啦

四、配置swagger扫描接口

1.了解其他属性

我们点击docket进去看源码，会发现，里面还有一些属性

为了更加全面的认识和使用swagger，我们将除了ApiInfo的其他属性也进行操作一下

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    //enable是否启动swagger
    .enable(true)
    .select()
    //RequestHandlerSelectors 配置要扫描的接口方式
    //basePackage指定要扫描的包
    //any扫描全部
    //none全都不扫描
    //withClassAnnotation：扫描类上的注解
    .apis(RequestHandlerSelectors.basePackage("org.example.controller"))
    //paths() 过滤的路径
    .paths(PathSelectors.ant("/hello/**"))
    .build();
}

可以进行自己不同的东西进行测一测，然后注意就是select后面要先build，中间的其他方法才能调用哦

2.控制swagger的开启

控制开启的好处：       

（1）防止接口暴露：Swagger能够自动生成和展示API接口文档，这在开发或测试环境下非常有用，但在生产环境中，如果Swagger被开启，可能会将API接口暴露给潜在的攻击者，增加安全风险。因此，在生产环境下通常需要关闭Swagger，以减少接口暴露的风险。

（2）减少资源消耗：Swagger的生成和展示需要消耗一定的系统资源，包括CPU、内存和带宽等。在生产环境中，关闭Swagger可以释放这些资源，用于处理更重要的业务请求，从而提高系统的整体性能。

（3）简化配置管理：通过控制Swagger的开启，可以简化配置文件的管理。例如，可以为不同的环境创建不同的配置文件（如application-dev.yml、application-test.yml、application-pro.yml等），并在这些配置文件中指定Swagger的开启状态。这样可以方便地根据不同环境的需求来切换Swagger的开启状态。

思路：

首先要判断什么环境下使用，然后用enable这个方法，控制是否开启swagger的，利用这个参数的true或者是flase来控制

实现：

配一下这三个文件：

application.yml -------------------------- 全局配置文件
application-dev.yml -------------------- 开发环境配置文件
application-pro.yml -------------------- 生产环境配置文件

 application.yml是配置全文的，在里面我们配置了dev，说明是开启状态，重新启动项目刷新页面依然可以访问，如果把application.yml配置的 spring.profiles.active=dev 这行删掉，你再去访问是访问不到的

到这就可以实现控制

五、配置API文档分组

1. 配置一个分组

重启刷新页面，就可以看到组别从“default”变成了“小赖同学”

 2. 配置多个分组

 重启刷新页面，就可以看到多个组别 

六、相关常用注解

1.实体类配置常用注解

创建一个pojo包，写一个User实体类，并为实体类命名以及属性的命名（注意app和pojo包同级）

package org.example.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("年龄")
    public int age;
}

在Controller里面写个接口，并进行调用测试

    //只要我们的接口中，返回值存在实体类，他就会被扫描到swagger
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }

重启项目刷新页面，会在model查看到我们的实体类信息

2. 方法所用到的注解

    @ApiOperation("HELLO控制")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String name){
        return "hello2"+name;
    }

3.注解总结 

@ApiModel --- 通常用于Java类的顶部，这些类代表API响应或请求体中的模型对象

@ApiModelProperty --- 主要用于Java类的字段（属性）上。通过使用这个注解，开发人员可以为这些字段提供丰富的元数据描述，如字段的名称、描述、数据类型、是否必填、示例值等

@ApiOperation --- 主要用于Java控制器（Controller）类中的方法上。通过在接口方法上添加这个注解，可以为该方法提供接口名称、描述、参数信息、返回类型等

@ApiParam --- 主要用于Java控制器（Controller）类中的方法参数上，但也可以用于方法本身或字段说明

各个注解的参数可以打开对应的源码进行查看

七、接口调用

在页面中，我们可以看到不同请求方法的各个接口，点击进去

还有一些有参数的就对应写参数即可

以上就是swagger的基本使用啦~希望能帮到求学者~