swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统）

web工程部分框架信息：spring springmvc swagger springfox maven

参考文档：
https://www.cnblogs.com/exmyth/p/7183753.html
https://www.cnblogs.com/arctictern/p/7498838.html
https://my.oschina.net/wangmengjun/blog/907679
http://springfox.github.io/springfox/docs/current/

pom.xml 对于 swagger-ui 的依赖

        <!-- https://mvnrepository.com/artifact/com.mangofactory/swagger-springmvc -->
        <dependency>
            <groupId>com.mangofactory</groupId> <artifactId>swagger-springmvc</artifactId> <version>0.9.5</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-petstore --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-petstore</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-data-rest</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-bean-validators</artifactId> <version>2.7.0</version> </dependency> <!-- https://mvnrepository.com/artifact/com.google.guava/guava --> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>23.4-jre</version> </dependency> <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-javadoc-plugin --> <dependency> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>3.0.0</version> </dependency>

工程结构（仅作为参考）

配置步骤如下：

1、创建 swagger 的配置类（如果要自定义一些内容，请参考官网 API 的描述）

@Configuration      // 这是控制开关
@EnableSwagger2     // 这是用了 swagger2
@EnableWebMvc // 这是因为工程用的 springmvc @ComponentScan(basePackages = {"controller"}) //这里也许可以不用，暂没去求证 public class SwaggerConfig { /** * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple swagger groups i.e. same code base multiple swagger resource listings. */ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() //select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现 .apis(RequestHandlerSelectors.any()) //扫描指定包内所有Controller定义的Api，并产生文档内容（除了被@ApiIgnore指定的请求）。 .paths(PathSelectors.any()) .build() .apiInfo(apiInfo()); //用来创建该Api的基本信息（这些基本信息会展现在文档页面中） } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("Spring-mvc中使用Springfox集成Swagger2构建APIs").build(); } }

2、在 spring-mvc.xml 中添加扫描文件的信息

    <!-- Enables swgger ui -->
    <bean class="swagger.swaggerConfig.SwaggerConfig" /> <!-- 这里其实是为了解决静态资源访问的问题, 这是一种解决方式 --> <mvc:default-servlet-handler/>

3、在 spring-mvc的拦截器做处理，即在 web.xml 中追加

 <!-- springMVC核心配置 -->
    <servlet>
        <servlet-name>dispatcherServlet</servlet-name> <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class> <init-param> <param-name>contextConfigLocation</param-name> <!--spingMVC的配置路径 --> <param-value>classpath:springmvc/spring-mvc.xml</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <!-- 拦截设置 --> <servlet-mapping> <servlet-name>dispatcherServlet</servlet-name> <url-pattern>*.do</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>default</servlet-name> <url-pattern>/swagger-ui.html</url-pattern> </servlet-mapping> <!--<servlet-mapping>--> <!--<servlet-name>default</servlet-name>--> <!--<url-pattern>*.png</url-pattern>--> <!--</servlet-mapping>--> <!--<servlet-mapping>--> <!--<servlet-name>default</servlet-name>--> <!--<url-pattern>*.js</url-pattern>--> <!--</servlet-mapping>--> <!--<servlet-mapping>--> <!--<servlet-name>default</servlet-name>--> <!--<url-pattern>*.css</url-pattern>--> <!--</servlet-mapping>--> <servlet-mapping> <servlet-name>dispatcherServlet</servlet-name> <url-pattern>/</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>dispatcherServlet</servlet-name> <url-pattern>/v2/api-docs</url-pattern> </servlet-mapping>

4、从https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里

5、并打开复制过来的 index.html，修改 url

6、再在 spring-mvc.xml 中追加资源映射

    <mvc:resources mapping="*.html" location="apidoc/resources"/> <mvc:resources mapping="/**" location="apidoc/"/> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars"/> <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />

此时 spring-mvc.xml 看起来可能就像这样：

注意下述内容最好保持一致（因为我也没花时间去求解，之前因为一些处理，访问时遇到了"base URL......"吧啦吧啦的模态框）

7、启动运行成功后，访问地址 http://localhost:8080/swagger-ui.html
看起来像这样子：

个人目前对于 swagger 的用途（优缺点）理解

优点

1、不用在 coding 之后再去写接口文档，可以实时同步更新
2、不需要重复造轮子，写解析器（当然定制化的会轻便灵活得多）
3、可以用于后台的 web 接口的快速调试
4、有配套的工具来支撑扩展（见 swagger 的官网 tools 栏目）

缺点

1、有学习成本（如环境配置、注解使用等）
2、可能会和真实开发的工程存在组件的冲突
3、（最明显的）工作量可能会增加，这个需要开发岗的慎重评估。比如非标准的 restful api设计；工程的复杂度设计如 DTO 完全就是对应 BO 时，需要拆成标准的设计；API 编写的工作量受框架约束等等
4、文档界面虽美观，但是阅读性不一定直观
5、没有自研的工具给力，对于测试工程师来说需要考虑使用 swagger 后解决方案
6、工程之间是隔离的