swagger配置

swagger简介

Swagger 是一个简单、强大的 RestfulAPI 文档生成管理工具，通过 swagger-spring 项目实现了与 Sping MVC 框架的无缝集成功能，方便生成 spring restful 风格的接口文档，在项目中集成这个工具，根据我们自己的配置信息能够自动为我们生成一个 API 文档展示页，可以在浏览器中直接访问查看项目的接口信息（如下图 1 所示），同时 swagger-ui 还可以测试 spring restful 风格的接口功能，可以对项目提供的每一个 API 接口进行相应的测试。Swagger生成的API文档是实时更新的， API接口有任何改动都会在文档中及时的表现出来。其官方网站为：http://swagger.io/。

• 前后端分离

前端-------->前端控制层,视图层
    ↑
    |
    | Restful API
    |
↓
后端-------->后端控制层,服务层,数据访问层

• 前后分离好处:相对独立且松耦合
• 导致问题
  • 前后端集成--->CI/CD
    • 前端或者后端无法做到"及时商量,尽早解决",最终导致集中爆发
    • CI:持续集成(Continuous integration)是一种软件开发实践，每次集成都通过自动化的构建（包括编译，发布，自动化测试）来验证，从而尽早地发现集成错误。
    • CD:持续部署（continuous deployment）是通过自动化的构建、测试和部署循环来快速交付高质量的产品。
• 解决方案
  • 首先定义schema,并实时跟踪最新的API,降低集成风险
• swagger
  • Restful API文档在线自动生成器--->API文档与API定义自动更新
  • 直接运行,在线测试API
  • 支持多种语言(比如:java,php等)
  • 官网https://swagger.io
• spring集成swagger--->springfox
  • springfox-swagger2
  • swagger-springmvc
• swagger演示
  • http://itrp.cn/biz/swagger-ui.html
  • 需要将前端工程及缓存配置注释掉
  •  

 

 

项目中集成swagger

• 项目环境
  • jdk1.8--->swagger2必须使用1.8以上版本jdk
  • spring-4.1.7
  • mybatis-3.3.2
• springmvc集成springfox-swagger2构建Restful API
  • maven依赖
    • springfox-swagger2
    • springfox-swagger-ui
    • guawa:google相关
    • mapstruct-jdk8:对象结构相关
    • jackson
      • jackson-core
      • jackson-databind
      • jackson-annotations

1.     <groupId>io.springfox</groupId>
2.    <artifactId>springfox-swagger2</artifactId>
3.     <version>2.4.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-aop</artifactId>
        </exclusion>
        <exclusion>
            <groupId>com.fasterxml</groupId>
            <artifactId>classmate</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>spring-aop</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>19.0</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-jdk8</artifactId>
    <version>1.1.0.Final</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>${jackson.verson}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>${jackson.verson}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>${jackson.verson}</version>
</dependency>

 

• 集成配置步骤
  • 在pom.xml文件中添加swagger2相关依赖
  • swagger2配置类:SwaggerConfig.java(官网下载)
    • @ComponentScan:设置swagger扫描包
    • @EnableSwagger2:使swagger2生效
    • @Configuration:自动在本类上下文加载一些环境变量信息
  • springmvc配置文件

• 1. 使用的页面是静态资源,配置此注解,不让springmvc进行拦截-->
     <mvc:default-servlet-handler/>
     <!--添加指定扫描,让swagger的注解生效-->
     <context:component-scan/>
• swagger具体应用
  • api加入swagger
    • 通过在api上添加注解实现,api文件的同步效果
    • @Api
      • 表明可供swagger展示的接口类(用在类上面)
    • @ApiOperation
      • 描述api方法(用在方法上面)
    • @ApiParam
      • 单个参数描述
    • @ApiModel
      • 用对象接收参数(用在类上面)
    • @ApiModelProperty
      • 用对象接收参数时,描述对象的一个字段(用在属性上面)
    • SystemCommentController介绍

nginx配置访问swagger

• 访问swagger页面
  • http://ip:port/{context-path}/swagger-ui.html
• 问题
  • 生产环境下,只开放80端口,通过tomcat无法访问swagger
• 解决方案
  • 通过nginx配置swagger的访问
    • 修改nginx.conf文件
• swagger在线帮助文档

http://docs.swagger.io/swagger-core/apidocs