Java API框架Swagger 使用详解

Swagger 简介

1.最流行的API 框架
2.RestFul Api 文档在线自动生成工具
3.直接运行，可以在线测试API接口
4.支持多种语言

添加swagger依赖

pom.xml文件添加下面依赖

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

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

springboot集成Swagger

通过springboot 集成swagger ，创建配置类，使用类名上使用 @Configuration 、@EnableSwagger2 即可启动swagger ，并开启默认配置。

package com.swagger.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author Yangbo
 * @version 1.0.0
 * @ClassName SwaggerConfig.java
 * @Description TODO
 * @createTime 2022年08月17日 10:31
 */
@Configuration
@EnableSwagger2  //开启Swagger
public class SwaggerConfig {
//配置文件不写，执行默认配置

}

启动项目
访问该连接，进入swagger ui页面
http://localhost:8080/swagger-ui.html

配置swagger ui页面信息

启动swagger 后可以通过配置文件更改 swagger-ui 页面信息 ，如个人邮箱，团队地址，作者信息，swagger 版本信息，api接口版本信息等。 contact 对象为作者信息， ApiInfo为swageer 标题,版本号等信息。

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

/**
 * @author Yangbo
 * @version 1.0.0
 * @ClassName SwaggerConfig.java
 * @Description TODO
 * @createTime 2022年08月17日 10:31
 */
@Configuration
@EnableSwagger2  //开启Swagger
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("Yangbo", "https://blog.csdn.net/qq_46645840/article/details/126368940", "xxx@qq.com");      //作者信息

        return new ApiInfo("Yangbo的swagger API文档",        //标题
                "文档描述",          //描述
                "v1.0",           //api版本
                "https://blog.csdn.net/qq_46645840/article/details/126368940",               //团队地址
                contact,         //作者信息
                 "Apache 2.0",           
                  "http://www.apache.org/licenses/LICENSE-2.0", 
                  new ArrayList<>());
    }


}

更改配置后的进入swagger ui页面，已经为更改后的

配置扫描路径

配置扫描路径,扫描指定的接口
RequestHandlerSelectors.basePackage() 为包扫描最为常用
RequestHandlerSelectors.withMethodAnnotation() 为方法注解扫描,扫描使用了该注解的方法
RequestHandlerSelectors.withClassAnnotation() 扫描类上的注解 ，参数是一个注解的反射对象
paths(PathSelectors.ant()). //过滤路径
enable(true) //是否启用 swageer
示例代码如下：

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

    //配置swagger 的bean 实力
    @Bean
    public Docket docket() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())             //swagger信息
                .enable(true)  //是否启用 swageer
                .select()                            //扫描
                //RequestHandlerSelectors配置要扫描接口的方式
                       //.apis(RequestHandlerSelectors.basePackage("com.swagger.controller")).build();   指定要扫描的包
                       //.apis(RequestHandlerSelectors.any().build(); 扫描全部
                       //.apis(RequestHandlerSelectors.none().build();   不扫描
                       //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)    扫描类上的注解 ，参数是一个注解的反射对象
                       // .apis(RequestHandlerSelectors.withMethodAnnotation(getMapping.class)     扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller")) //api扫描方式
                .paths(PathSelectors.ant("/")).                         //过滤路径
                build();

    }

配置api 分组

配置api的分组，分组单独互不影响开发人员可以自己定义。

分组方法

gourpName()

创建分组代码示例

    @Bean
    public Docket docketGroup1(){
        //分组 A组
        return   new Docket(DocumentationType.SWAGGER_2).groupName("A");

    }
    @Bean
    public Docket docketGroup2(){
        //分组 B组
        return   new Docket(DocumentationType.SWAGGER_2).groupName("B");

    }

实体类配置