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