swagger

了解更多

一、簡介

Swagger是一種REST APIs的簡單但強大的表示方式叫倍，標(biāo)準(zhǔn)的偷卧，語言無關(guān)，這種表示方式不但人可讀吆倦，而且機器可讀听诸。可以作為REST APIs的交互式文檔蚕泽，也可以作為REST APIs的形式化的接口描述晌梨，生成客戶端和服務(wù)端的代碼。
docs ： swagger docs

二须妻、為什么選擇Swagger

1. 使用Swagger UI生成的界面比Javadoc生成的界面美觀
2. swagger可以實時同步API文檔(代碼修改后仔蝌，文檔同步修改)
3. swagger解析速度快，效率高(使用輕量級數(shù)據(jù)交換格式JSON)
4. 對現(xiàn)有SpringMVC工程支持友好
5. Swagger可以充當(dāng)前后端交流的重要橋梁荒吏，方便快捷敛惊。很實用。
6. Swagger項目允許你生產(chǎn)司倚，顯示和消費你自己的RESTful服務(wù)豆混。不需要代理和第三方服務(wù)。是一個依賴自由的資源集合动知，它能通過Swagger API動態(tài)的生成漂亮的文檔和沙盒,因為Swagger UI沒有依賴皿伺，你可以把他部署到任何服務(wù)器環(huán)境或者是你自己的機器。

三盒粮、如何使用Swagger

3.1Swagger UI簡介

Swagger UI是Swagger中用于顯示Rest接口文檔的項目鸵鸥，項目由一組HTML，JavaScript和CSS組成，沒有外部依賴妒穴。Swagger UI可以根據(jù)Swagger Spec的json動態(tài)生成漂亮的幫助文檔宋税。支持常見瀏覽器。
(Swagger Spec是Swagger用于描述REST APIs的語言讼油，可用json/yaml表示)
了解更多

1杰赛、支持API自動生成同步的在線文檔，這些文檔可用于項目內(nèi)部API審核方便測試人員了解API
2矮台、這些文檔可作為客戶產(chǎn)品文檔的一部分進行發(fā)布
3乏屯、支持API規(guī)范生成代碼，生成的客戶端和服務(wù)器端骨架代碼可以加速開發(fā)和測試速度

3.2開發(fā)步驟

參考

①添加依賴

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
      </dependency>
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
      </dependency>

其中swagger.version自由控制

②寫Java配置類

@PropertySource("classpath:swagger.properties")
@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

③集成Swagger UI到工程中

1.從github上下載swagger-ui的zip包
2.復(fù)制dist文件夾下的內(nèi)容到webapp目錄下
3.修改index.xml的預(yù)訪問地址為自定義的

4.修改web.xml文件中過濾器的匹配路徑為/
5.因為swagger-ui項目都是靜態(tài)資源校辩，restful形式的攔截方法會將靜態(tài)資源進行攔截處理窘问，所以在springmvc配置文件中需要配置對靜態(tài)文件的處理方式。
<mvc:default-servlet-handler/>

此舉是為了體驗最新版的swagger-ui召川，并且可以高度自定義內(nèi)容南缓，其實在springfox-swagger-ui中已經(jīng)集成了大多數(shù)資源胸遇，如html頁面和js文件等荧呐，當(dāng)存在注解@EnableSwagger2時，就可以使用http://ip:host/swagger-ui.html查看接口文檔

3.3注解說明

Javadocs for annotations with the current release are here
本文只簡單介紹常用的部分注解及其屬性