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 的依赖

  1.         <!-- https://mvnrepository.com/artifact/com.mangofactory/swagger-springmvc -->
  2.         <dependency>
  3.             <groupId>com.mangofactory</groupId>
  4.             <artifactId>swagger-springmvc</artifactId>
  5.             <version>0.9.5</version>
  6.         </dependency>
  8.         <dependency>
  9.             <groupId>io.springfox</groupId>
  10.             <artifactId>springfox-swagger2</artifactId>
  11.             <version>2.7.0</version>
  12.         </dependency>
  14.         <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
  15.         <dependency>
  16.             <groupId>io.springfox</groupId>
  17.             <artifactId>springfox-swagger-ui</artifactId>
  18.             <version>2.7.0</version>
  19.         </dependency>
  21.         <!-- https://mvnrepository.com/artifact/io.springfox/springfox-petstore -->
  22.         <dependency>
  23.             <groupId>io.springfox</groupId>
  24.             <artifactId>springfox-petstore</artifactId>
  25.             <version>2.7.0</version>
  26.         </dependency>
  28.         <dependency>
  29.             <groupId>io.springfox</groupId>
  30.             <artifactId>springfox-data-rest</artifactId>
  31.             <version>2.7.0</version>
  32.         </dependency>
  34.         <dependency>
  35.             <groupId>io.springfox</groupId>
  36.             <artifactId>springfox-bean-validators</artifactId>
  37.             <version>2.7.0</version>
  38.         </dependency>
  40.         <!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
  41.         <dependency>
  42.             <groupId>com.google.guava</groupId>
  43.             <artifactId>guava</artifactId>
  44.             <version>23.4-jre</version>
  45.         </dependency>
  47.         <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-javadoc-plugin -->
  48.         <dependency>
  49.             <groupId>org.apache.maven.plugins</groupId>
  50.             <artifactId>maven-javadoc-plugin</artifactId>
  51.             <version>3.0.0</version>
  52.         </dependency>

工程结构（仅作为参考）
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图1

配置步骤如下：

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

  1. @Configuration      // 这是控制开关
  2. @EnableSwagger2     // 这是用了 swagger2
  3. @EnableWebMvc   // 这是因为工程用的 springmvc 
  4. @ComponentScan(basePackages = {"controller"})     //这里也许可以不用，暂没去求证
  5. public class SwaggerConfig {
  6.     /**
  7.      * 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.
  8.      */
  9.     @Bean
  10.     public Docket customDocket() {
  11.         return new Docket(DocumentationType.SWAGGER_2)
  12.                 .select()            //select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
  13.                 .apis(RequestHandlerSelectors.any()) //扫描指定包内所有Controller定义的Api，并产生文档内容（除了被@ApiIgnore指定的请求）。
  14.                 .paths(PathSelectors.any())
  15.                 .build()
  16.                 .apiInfo(apiInfo()); //用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
  17.     }
  19.     private ApiInfo apiInfo() {
  20.         return new ApiInfoBuilder().title("Spring-mvc中使用Springfox集成Swagger2构建APIs").build();
  21.     }
  23. }

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

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

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

  1.  <!-- springMVC核心配置 -->
  2.     <servlet>
  3.         <servlet-name>dispatcherServlet</servlet-name>
  4.         <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
  5.         <init-param>
  6.             <param-name>contextConfigLocation</param-name>
  7.             <!--spingMVC的配置路径 -->
  8.             <param-value>classpath:springmvc/spring-mvc.xml</param-value>
  9.         </init-param>
  10.         <load-on-startup>1</load-on-startup>
  11.     </servlet>
  12.     <!-- 拦截设置 -->
  13.     <servlet-mapping>
  14.         <servlet-name>dispatcherServlet</servlet-name>
  15.         <url-pattern>*.do</url-pattern>
  16.     </servlet-mapping>
  18.     <servlet-mapping>
  19.         <servlet-name>default</servlet-name>
  20.         <url-pattern>/swagger-ui.html</url-pattern>
  21.     </servlet-mapping>
  23.     <!--<servlet-mapping>-->
  24.         <!--<servlet-name>default</servlet-name>-->
  25.         <!--<url-pattern>*.png</url-pattern>-->
  26.     <!--</servlet-mapping>-->
  28.     <!--<servlet-mapping>-->
  29.         <!--<servlet-name>default</servlet-name>-->
  30.         <!--<url-pattern>*.js</url-pattern>-->
  31.     <!--</servlet-mapping>-->
  33.     <!--<servlet-mapping>-->
  34.         <!--<servlet-name>default</servlet-name>-->
  35.         <!--<url-pattern>*.css</url-pattern>-->
  36.     <!--</servlet-mapping>-->
  38.     <servlet-mapping>
  39.         <servlet-name>dispatcherServlet</servlet-name>
  40.         <url-pattern>/</url-pattern>
  41.     </servlet-mapping>
  43.     <servlet-mapping>
  44.         <servlet-name>dispatcherServlet</servlet-name>
  45.         <url-pattern>/v2/api-docs</url-pattern>
  46.     </servlet-mapping>

4、从https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图2

5、并打开复制过来的 index.html，修改 url
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图3

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

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

此时 spring-mvc.xml 看起来可能就像这样：
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图4

注意下述内容最好保持一致（因为我也没花时间去求解，之前因为一些处理，访问时遇到了”base URL……”吧啦吧啦的模态框）
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图5
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图6

7、启动运行成功后，访问地址 http://localhost:8080/swagger-ui.html
看起来像这样子：
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图7
swagger-ui 系统配置过程（基于spring+springmvc+swagger+springfox配置 web-api 管理系统） - 图8

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

优点

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

缺点

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