狂神聲明 : 文章均為自己的學(xué)習(xí)筆記 , 轉(zhuǎn)載一定注明出處 ; 編輯不易 , 防君子不防小人~共勉 !?

Swagger學(xué)習(xí)筆記

課程目標(biāo)

• 了解Swagger的概念及作用
• 掌握在項(xiàng)目中集成Swagger自動(dòng)生成API文檔

Swagger簡(jiǎn)介

前后端分離? (前后端相對(duì)獨(dú)立且松耦合)

• 前端-->前端控制層 , 視圖層
• 前端和后端利用API接口進(jìn)行相應(yīng)協(xié)作(數(shù)據(jù)可能是json也可能是xml等等的...)
• 后端-->后端控制層 , 服務(wù)層 , 數(shù)據(jù)訪問(wèn)層

問(wèn)題 ?

• 前后端集成------CI/CD
  • 前端或后端無(wú)法做到 "及時(shí)協(xié)商 , 盡早解決" 最終導(dǎo)致問(wèn)題集中爆發(fā) .

解決方案

• 首先定義schema , 并實(shí)時(shí)跟蹤最新的API , 降低集成風(fēng)險(xiǎn) .

Swagger

• Restful API文檔在線自動(dòng)生成器-->API文檔與API定義同步更新
• 直接運(yùn)行 , 在線測(cè)試API
• 支持多種語(yǔ)言 (如 : java , php 等等)
• 官網(wǎng) : https:///

Spring集成Swagger -->springfox

• springfox-swagger2
• swagger-springmvc

項(xiàng)目中集成Swagger

項(xiàng)目環(huán)境 : JDK1.8 , Spring4.1.7 , Mybatis3.2.2

Spring MVC 集成springfox-swagger2構(gòu)建Restful API

• Maven依賴(lài)
  • springfox-swagger2
  • springfox-swagger-ui
  • guava
  • mapstruct-jdk8
  • jackson
    • jackson-core
    • jackson-databind
    • jackson-annotations

集成配置步驟

1. 在pom.xml文件中添加Swagger2相關(guān)的依賴(lài)
2. Swagger2配置類(lèi) : SwaggerConfig . java (官網(wǎng)下載)
   • @ComponentScan : 設(shè)置Swagger 掃描包
   • @EnableSwagger2 : 使Swagger2生效
   • @Configuration : 自動(dòng)在本類(lèi)上下文加載一些環(huán)境變量信息

     package dcc.core;
      
     import org.springframework.context.annotation.Bean;
     import org.springframework.context.annotation.Configuration;
     import org.springframework.web.servlet.config.annotation.EnableWebMvc;
      
     import springfox.documentation.builders.ApiInfoBuilder;
     import springfox.documentation.builders.RequestHandlerSelectors;
     import springfox.documentation.service.ApiInfo;
     import springfox.documentation.spi.DocumentationType;
     import springfox.documentation.spring.web.plugins.Docket;
     import springfox.documentation.swagger2.annotations.EnableSwagger2;
      
     @Configuration //聲明該類(lèi)為配置類(lèi)
     @EnableSwagger2 //聲明啟動(dòng)Swagger2
     @EnableWebMvc //聲明啟動(dòng)mvc
     public class SwaggerConfig{
         @Bean
         public Docket customDocket() {
             return new Docket(DocumentationType.SWAGGER_2)
                     .apiInfo(apiInfo())
                     .select()
                     .apis(RequestHandlerSelectors.basePackage("dcc"))//掃描的包路徑
                     .build();
         }
      
         private ApiInfo apiInfo() {
             return new ApiInfoBuilder()
                     .title("DCC API接口")//文檔說(shuō)明
                     .version("1.0.0")//文檔版本說(shuō)明
                     .build();
         }
     }

3. Spring MVC配置文件

   <!-- 激活@controller模式 -->
   <mvc:annotation-driven />
    
   <!-- 開(kāi)啟靜態(tài)文件 默認(rèn)攔截器 -->
   <mvc:default-servlet-handler/>
   
   添加指定掃描 : < context:component-scan />

具體運(yùn)用

API加入Swagger

• 通過(guò)在API上添加注解實(shí)現(xiàn) , API文檔的同步效果
• @Api --> ( 表名可供Swagger展示的接口類(lèi) : 用在類(lèi)上面 )
• @ApiOperation --> ( 描述API方法 : 用在方法上面 )
• @ApiParam --> ( 單個(gè)參數(shù)描述 )
• @ApiModel --> ( 用對(duì)象接收參數(shù) : 用在類(lèi)上面 )
• @ApiModelProperty --> ( 用對(duì)象接收參數(shù)時(shí) , 描述對(duì)象的一個(gè)字段 ; 用在屬性上面 )

Nginx配置

• 訪問(wèn)Swagger界面
  • http://IP:port /{context-path}/swagger-ui.html
• 問(wèn)題
  • 生成環(huán)境下 , 只開(kāi)放80端口 , 通過(guò)Tomcat無(wú)法訪問(wèn)Swagger
• 解決方案
  • 通過(guò) Nginx 進(jìn)行Swagger 的訪問(wèn) (nginx.conf)
    • 注釋掉 server節(jié)點(diǎn)下的 root . 即前端靜態(tài)工程
    • 注釋掉 location 這個(gè)節(jié)點(diǎn)
    • 
  • http://IP/{context-path}/swagger-ui.html