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"/>