【Java】【组件使用】【Swagger2的基本使用】

时光与简

已于 2022-09-30 16:57:40 修改

阅读量1.8k

点赞数

分类专栏： Java 文章标签： java

于 2022-04-13 13:42:30 首次发布

本文链接：https://blog.csdn.net/qq_39248747/article/details/124144466

版权

Java 专栏收录该内容

8 篇文章 0 订阅

订阅专栏

【Java】【组件使用】【Swagger2的基本使用】

以下使用皆基于springboot项目。

一、Jar包的引入的两种方式

1.1、使用swagger官方提供的jar包

1.1.1、第一步在pom文件里引入2.9.2版本的jar包

<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从2.6.0版本开始不支持2.9.2版本的jar包，低于此版本的才可以引入此jar包

1.1.2、第二步添加配置文件

1.1.3、第三步添加注解

在起始类添加注解@EnableSwagger2：

或者在Swagger配置文件添加注解@EnableSwagger2：

注：任意一个即可，但不能不写

1.2、使用非官方封装的包（-）

这个和官方的swagger2的区别就在于，自动化配置，引入jar包和添加注解即可使用，当然，如果需要个性化操作，就需要自己在yml文件添加配置。

1.2.1、第一步 jar包引入

<!-- https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.1.RELEASE</version>
</dependency>

1.2.2、第二步增加注解@EnableSwagger2Doc

1.2.3、可选配置

yml格式配置：

1.2.4、界面

和原生swagger界面并无区别

1.3、使用非官方封装的包（二）

和上面一个很相似，不过在这基础上，又参考了swagger-bootstrap-ui
注：1.X 版本需要在启动类添加 `@EnableSwagger2Doc` 但是 2.X 版本后无需添加
https://gitee.com/battcn/spring-boot-starter-swagger/

<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.1.5-RELEASE</version>
</dependency>

二、增强版-可视化界面（支持文档导出）

http://${host}:${port}/doc.html

2.1、老版的使用

2.1.1、jar包的引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

2.1.2、在配置文件或者启动类添加注解@EnableSwaggerBootstrapUI

2.1.3、界面

2.2、新版的使用

2.2.1、jar包的引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

2.2.2、界面

2.3、如果被拦截器拦截的处理方式

首先，swagger配置文件实现WebMvcConfigurer

然后重写addResourceHandlers方法，并添加:

  registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

示例:

   @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    }

三、使用注意点

3.1、项目进行了反向代理时的处理

配置反射路径时并没有将context-path的路径映射，就需要这里代码：

四、注解的使用

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述
@ApiModel：用对象实体来作为入参
@ApiProperty：用对象接实体收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams： 多个请求参数

五、Swagger配置文件示例

package com.jh.plug.config;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.paths.RelativePathProvider;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import javax.servlet.ServletContext;
import java.util.Collections;
import java.util.HashSet;
import java.util.Set;

@EnableSwagger2
@Configuration
//Profile是方法1（只在dev和test环境下开启）
//@Profile({"dev","test"})
public class SwaggerConfig implements WebMvcConfigurer {

    @Bean("shopApi")
    public Docket createRestApi(ServletContext servletContext) {
        return new Docket(DocumentationType.SWAGGER_2)
//                .pathProvider(new RelativePathProvider(servletContext) {
//                    @Override
//                    public String getApplicationBasePath() {
//                        return "/jherp-shop-api";
//                    }
//                })
                .groupName("shop")// 不能为中文，否则termsOfServiceUrl打不开
                .consumes(DEFAULT_PRODUCES_AND_CONSUMES)
                .produces(DEFAULT_PRODUCES_AND_CONSUMES)
                .useDefaultResponseMessages(false)//不使用默认相应code
                .apiInfo(apiInfo())// 用于生成API信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jh.plug"))// 用于指定扫描哪个包下的接口
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//为有@Api注解的Controller生成API文档

//				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                //创建
                .build();
    }

    /**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("鲸汇平台对接项目API") //  可以用来自定义API的主标题
                .description("<p>鲸汇平台对接项目SwaggerAPI管理，主要用于测试平台接口连通性。</p>") // 可以用来描述整体的API
                .termsOfServiceUrl("") // 用于定义服务的域名
                .version("1.0") // 可以用来定义版本。
                .build(); //
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

    }

    //配置content type
    private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES =
            new HashSet<>(Collections.singletonList("application/json"));//,"application/xml"，只需要json格式

    @Bean
    public UiConfiguration uiConfiguration() {
        return UiConfigurationBuilder.builder()
                // 隐藏UI上的Models模块：-1为不显示，默认为0显示
                .defaultModelsExpandDepth(0)
                .build();
    }
}