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>

工程结构（仅做为参考）

配置步骤以下：

一、建立 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(); } }

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

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

三、在 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>

四、从https://github.com/swagger-api/swagger-ui 获取其全部的 dist 目录下东西放到须要集成的项目里

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

六、再在 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......"吧啦吧啦的模态框）



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

---

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

优势

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

缺点

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