springboot快速集成swagger2，支持离线文档导出

最新推荐文章于 2024-09-07 22:27:57 发布

WoddenFish

最新推荐文章于 2024-09-07 22:27:57 发布

阅读量750

点赞数 1

分类专栏： java项目级组件文章标签： springboot swagger2 swagger2文档导出

本文链接：https://blog.csdn.net/WoddenFish/article/details/107341184

版权

java项目级组件专栏收录该内容

21 篇文章 1 订阅

订阅专栏

话不多说，直接上步骤！离线文档集成选择knife4j，非常强大。

1、导入maven依赖，版本可以自己更换

<!--引入swagger相关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>
<!-- 离线文档集成 -->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
   <version>2.0.4</version>
</dependency>

2、swagger配置，此处将静态资源放行以及扫包配置、跨域配置全部集成到了一个类。

package com.edi.framework.web.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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;

/**
 * *************************************************************************
 * <pre>
 * 文件名称:  SwaggerConfig.java
 * 包   路   径：  com.edi.framework.web.config
 * </pre>
 * <pre>
 * 类描述:
 * Revision : Revision: 2.0.0
 * 创建人： gdq
 * 创建时间：2020年07月09日 13:37:00
 * 修改人：gdq
 * 修改时间：2020年07月09日 13:37:00
 * </pre>
 *
 * <pre>
 *  1. 修改记录：
 *    -----------------------------------------------------------------------------------------------
 *              时间                      |       修改人            |         修改的方法                       |         修改描述
 *    -----------------------------------------------------------------------------------------------
 *                  		|                 |                           |
 *    -----------------------------------------------------------------------------------------------
 * </pre>
 * *************************************************************************
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig extends WebMvcConfigurationSupport {

    /**
     * <p>方法名称: addResourceHandlers | 描述: 静态资源访问</p>
     *
     * @param registry
     * @return void
     * @author: gdq
     * @date:   2020/7/14 4:10 PM
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        //上述两个为swagger的静态资源，下方的配置可以可无，可以随意更改适配你的项目情况
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/META-INF/resources/");

    }

    /**
     * <p>方法名称: addCorsMappings | 描述: 跨域支持</p>
     *
     * @param registry
     * @return void
     * @author: gdq
     * @date:   2020/7/14 4:11 PM
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowCredentials(true)
                .allowedMethods("GET", "POST", "DELETE", "PUT", "PATCH")
                .maxAge(3600);
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
//                .apis(RequestHandlerSelectors.basePackage("com.edi.framework.web.controller.question"))  //扫描包
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))  //只扫描有api注解的类
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //只扫描有ApiOperation注解的方法
                .paths(PathSelectors.any())
                .build()
                .enable(true);
    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                .title("RESTful API")
                .description("快速集成swagger2")
                .termsOfServiceUrl("http://localhost:8088/swagger-ui.html")
                .contact(new Contact("gdq", "http://localhost:8088", "gaodeqiang@ec.com.cn"))
                .version("2.0.0")
                .build();
    }
}

3、至此已经集成完毕，启动项目，原始swagger2文档访问 http://localhost:端口/swagger-ui.html，支持文档导出功能的访问链接：http://localhost:端口/doc.html ，本人更喜欢后者。

4、正式使用swagger，将注解加入到需要生成文档的类、方法或参数上。

swagger2 注解整体说明
@API: 请求类的说明
@ApiOperation: 方法的说明
@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明
@ApiResponses,@ApiResponse: 方法返回值的说明
@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息
@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

@API 其它属性配置:
属性名称	备注
value	url 的路径值
tags	如果设置这个值、value 的值会被覆盖
description	对 api 资源的描述
basePath       	基本路径
position            	如果配置多个 Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes 	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为 true ，将在文档中隐藏

实际调用：

import com.edi.framework.core.utils.json.JsonUtil;
import com.edi.framework.qn.db.entity.EdiQnResultUser;
import io.swagger.annotations.*;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

/**
 * *************************************************************************
 * <pre>
 * 文件名称:  SwaggerController.java
 * </pre>
 * <pre>
 * 类描述:
 * Revision : Revision: 1.1
 * 创建人： gdq
 * 创建时间：2020年07月31日 15:19:00
 * 修改人：gdq
 * 修改时间：2020年07月31日 15:19:00
 * </pre>
 *
 * <pre>
 *  1. 修改记录：
 *    -----------------------------------------------------------------------------------------------
 *              时间                      |       修改人            |         修改的方法                       |         修改描述
 *    -----------------------------------------------------------------------------------------------
 *                  		|                 |                           |
 *    -----------------------------------------------------------------------------------------------
 * </pre>
 * *************************************************************************
 */
@Api(tags="swagger测试模块",basePath = "/V2")
@Controller
@RequestMapping("/swagger")
@ResponseBody
public class SwaggerController {

    @ApiOperation(value = "获取用户")
    @GetMapping("/user")
    @ApiImplicitParams({
            @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
            @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
            @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="int")
    })
    @ApiResponses({
            @ApiResponse(code = 400, message = "参数缺失"),
            @ApiResponse(code = 404, message = "请求URL不存在")
    })
    public EdiQnResultUser userGet(String mobile ,String password,int age){
        return new EdiQnResultUser();
    }
}