springmvc引入swagger2

swagger2

简介

​ API Developmentfor Everyone。

​ Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.

​ Find out how Swagger can help you design and document your APIs at scale.

​ 简单来说就是一个以springmvc注解驱动为主生成在线文档的工具。

常用网站

• 官网

  官网入口：https://swagger.io/

  官网文档：https://swagger.io/docs/

• springmvc引入swagger2

  引入指南：https://blog.csdn.net/weixin_38501485/article/details/80704761

  Swagger2与通用的Spring MVC Controller冲突：https://blog.csdn.net/qq_37581282/article/details/90384674

springmvc怎么引入swagger2

写在开头

swagger2引入的核心功能主要是如下三个：

在线接口界面/swagger-ui.html

​ 主要是把springfox-swagger-ui-2.6.1.jar包里的页面内容注册成请求

在线文档数据接口/v2/api-docs

​ 主要是把springfox.documentation.swagger2.web.Swagger2Controller注册如spirngmvc容器，此部分可以通过springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration进行整合

动态扫描注册接口的后台功能

​ 主要是针对springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration的整合

实操过程

引入jar包

备注：此处以spring4.1.5为基础引入，swagger2版本为2.6.1

classmate-1.4.0.jar
guava-18.0.jar
spring-plugin-core-1.2.0.RELEASE.jar
spring-plugin-metadata-1.2.0.RELEASE.jar
springfox-core-2.6.1.jar
springfox-spi-2.6.1.jar
springfox-schema-2.6.1.jar
springfox-spring-web-2.6.1.jar
springfox-swagger2-2.6.1.jar
springfox-swagger-common-2.6.1.jar
springfox-swagger-ui-2.6.1.jar
swagger-annotations-1.5.10.jar
swagger-models-1.5.10.jar

如上内容也可以通过maven引入

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

编写配置类

import lombok.Data;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Description swagger配置类
 * @Author chendeming
 * @Date 2021/5/4
 * @Version 1.0
 **/
@Configuration
@EnableSwagger2
@Data
public class SwaggerConfig extends WebMvcConfigurationSupport {
		// 是否开启swagger2，正式环境最好用false
    private boolean enable = true;
    private String scan = "扫包路径"; 
    private String title = "应用名称";
    private String description = "简要说明";
    private String version = "1.0";
    private String contract = "联系方式";

    @Bean
    public Docket api() {
        // 创建注解
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
//                .enable(isEnable())
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage(getScan()))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
//        Contact contact = new Contact(getContractName(), getContractUrl(), getContractEmail());
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title(getTitle())
                //文档描述
                .description(getDescription())
                //联系方式
                .contact(contract)
                //版本号
                .version(getVersion())
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 注册swagger2页面资源
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

将配置类注册到容器中

这里需要注意：SwaggerConfig的bean一定要和@Controller、@RestController等请求放在同一个spring上下文中。

1、在springboot中引入

​ 直接用就行，保证springboot容器能够扫描到配置类SwaggerConfig即可

2、在springmvc中引入

​ 将SwaggerConfig以bean形式注册即可

3、在springmvc中引入，但是@Controller和@Service是分离注册的

​ 尤其注意！此处扫描@Controller和@Service的应该是两个xml，需要将SwaggerConfig以bean形式注册在扫描@Controller的那一个。

这个是扫描service的

<!-- scan service -->
<context:component-scan base-package="">
  <context:exclude-filter type="annotation" expression="org.springframework.stereotype.Controller" />  
  <context:exclude-filter type="assignable" expression="com.xxx.SwaggerConfig" />  
</context:component-scan>

这个是扫描controller的

<context:component-scan base-package=""  use-default-filters="false"> 
  <context:include-filter type="annotation" expression="org.springframework.stereotype.Controller" /> 
  <context:exclude-filter type="annotation" expression="org.springframework.stereotype.Service" />
</context:component-scan>
<bean id="swaggerDocumentConfig" class="com.xxx.SwaggerConfig"/>