青橙电商项目是典型的SSM框架开发,使用Dubbo分布式架构.包含网站前台和管理后台两大部分。网站前台
包含主站频道（首页、搜索、购物车及支付）、用户中心、秒杀、优惠券等频道。管理
后台包含商品、订单、库存、用户、运营、统计、财务、设置等功能。

1.系统结构图

image.png

项目目录结构:

image.png

2.导入Maven坐标

在qingcheng_web_manager模块的pom文件中添加依赖,此模块是后台管理的web模块.

        <!--swagger相关-->
        <!--springfox的核心jar包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--springfox-ui的jar包(里面包含了swagger的界面静态文件)-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--springfox依赖的jar包；如果你的项目中已经集成了无需重复-->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
        </dependency>

2.创建配置文件

在此模块源码目录下创建一个单独的package，然后创建SwaggerConfig.java文件

package com.qingcheng.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@WebAppConfiguration
@EnableSwagger2//重要！
@EnableWebMvc
@ComponentScan(basePackages = "com.qingcheng.controller")
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("青橙电商项目接口文档")
                .description("青橙电商项目接口测试")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .license("")
                .licenseUrl("")
                .build();
    }
}

3.在SpringMVC文件的配置文件中配置swagger

此项目采用的Dubbo分布式框架,所以在此模块下配置applicationContext-swagger.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
         http://www.springframework.org/schema/beans/spring-beans.xsd
         http://www.springframework.org/schema/mvc
         http://www.springframework.org/schema/mvc/spring-mvc.xsd
         http://www.springframework.org/schema/context
         http://www.springframework.org/schema/context/spring-context.xsd">

    <!--将静态资源交由默认的servlet处理-->
    <mvc:default-servlet-handler />
    <!--向容器自动注入配置-->
    <context:annotation-config />
    <!--自动扫描，使springMVC认为包下用了@controller注解的类是控制器-->
    <context:component-scan base-package="com.qingcheng.controller"/>
    <!--重要！将你的SwaggerConfig配置类注入-->
    <bean class="com.qingcheng.config.SwaggerConfig"/>
    <!--重要！配置swagger资源不被拦截-->
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

</beans>

4.修改web.xml文件中配置所有的请求都经DispatcherServlet处理

  <servlet>
    <servlet-name>springmvc</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <!-- 指定加载的配置文件 ，通过参数contextConfigLocation加载-->
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>classpath*:applicationContext*.xml</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>springmvc</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>

注意：这个地方必须配置，如果你配置的是*.XXX的形式会出现api-docs访问出错，这就会导致swagger-ui找不到api的有效路径。使swagger无法正常工作.

5.controller的配置，这里我只做简单的配置测试swagger是否正常工作

import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/brand")
@Api(value = "/brand", tags = "Brand品牌接口")
public class BrandController {

    @Reference
    private BrandService brandService;

    @ApiOperation(value = "获取品牌列表",notes = "查询所有品牌列表")
    @GetMapping("/findAll")
    public List<Brand> findAll() {
        return brandService.findAll();
    }


    @ApiOperation(value ="获取品牌分页列表",notes = "根据page和size查询分页")
    @GetMapping("/findPage")
    public PageResult<Brand> pageResult( int page, int size) {
        return brandService.findPage(page, size);
    }

运行：我这里使用Maven中的Tomcat8.5.16插件能够正常的工作

image.png