Swagger
使用文檔
G-SISI
2016-04-05
一、概述
swagger簡述
Swagger API架構，用于管理項目中API接口，屬目前最流行的API接口管理工具。 Swagger是一個開源架構(Web架構)，功能強大，UI界面漂亮，支援線上測試！
Swagger的目标是對REST API定義一個标準的和語言無關的接口，可讓人和計算機無需通路源碼、文檔或網絡流量監測就可以發現和了解服務的能力。當通過Swagger進行正确定義，使用者可以了解遠端服務并使用最少實作邏輯與遠端服務進行互動。與為底層程式設計所實作的接口類似，Swagger消除了調用服務時可能會有的猜測。
Swagger是一組開源項目，主要項目如下：
Swagger-tools:提供各種與Swagger進行內建和互動的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。
Swagger-core: 用于Java/Scala的的Swagger實作。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play架構進行內建。
Swagger-js: 用于JavaScript的Swagger實作。
Swagger-node-express: Swagger子產品，用于node.js的Express web應用架構。
Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger相容API動态生成優雅文檔。
Swagger-codegen：一個模闆驅動引擎，通過分析使用者Swagger資源聲明以各種語言生成用戶端代碼。
Swagger-editor：可讓使用者在浏覽器裡以YAML格式編輯Swagger API規範并實時預覽文檔。可以生成有效的Swagger JSON描述，并用于所有Swagger工具（代碼生成、文檔等等）中。
我們需要的:
1、Swagger可視化界面
Swagger-ui
2、相關jar包
classmate-1.1.0.jar、
guava-15.0.jar、
jackson-annotations-2.0.4.jar、
jackson-core-2.1.1.jar、
jackson-databind-2.1.1.jar、
jackson-jaxrs-json-provider-2.0.0.jar、
jackson-module-jaxb-annotations-2.0.0.jar、
jackson-module-scala-2.0.0.jar、
swagger-annotations-1.3.11.jar、
swagger-models-1.0.2.jar、
swagger-springmvc-1.0.2.jar
3、Maven依賴
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-models</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.11</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>15.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.0.4</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.1.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.1.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-jaxrs-json-provider</artifactId>
<version>2.0.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-module-jaxb-annotations</artifactId>
<version>2.0.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-module-scala</artifactId>
<version>2.0.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
<version>1.1.0</version>
</dependency>
注：最後3個jackson的包如果maven路徑錯誤，自行去查找，我的Demo不是Maven項目
二、使用方法
Demo配置：SpringMVC+Swagger+...
詳細步驟
Step 1
解壓Swagger-ui,找到裡面的dist檔案夾，将dist裡面的所有檔案copy到webapps下面，或者WEB-INF下。
當然你也可以建個檔案夾來放這些檔案，比如我建了swagger檔案夾來放這些東西。
Step 2
建立加載檔案 SwaggerConfig.java(名稱可以随意取)
SwaggerConfig.java
import org.springframework.context.annotation.Configuration;
importorg.springframework.beans.factory.annotation.Autowired;
importorg.springframework.context.annotation.Bean;
importcom.mangofactory.swagger.configuration.SpringSwaggerConfig;
importcom.mangofactory.swagger.models.dto.ApiInfo;
importcom.mangofactory.swagger.plugin.EnableSwagger;
importcom.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
@Configuration
@EnableSwagger
public class SwaggerConfig
{
private SpringSwaggerConfig springSwaggerConfig;
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
{
this.springSwaggerConfig = springSwaggerConfig;
}
@Bean
public SwaggerSpringMvcPlugin customImplementation()
{
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*?");
}
private ApiInfo apiInfo()
{
ApiInfo apiInfo = newApiInfo(
"==DemoProject Api Document==",
"寫點什麼",
"寫點什麼",
"寫點什麼",
"寫點什麼",
"寫點什麼");
returnapiInfo;
}
}
Step 3
添加配置
注：排程器攔截，Demo在這裡吃了虧，浪費了不少時間，定義預設的servlet映射;
原來是定義的是*.do，導緻Swagger無法讀取Json報Can`t read swagger JSON from …
Step 4
測試類
注解說明:
@Api(value=”/fc”description=”首頁”)
說明：@Api表示可執行測試的開放Api；value：表示請求位址，與@RequestMapping映射請求位址一緻；Description表示對該Api進行描述
@ApiOperation(value=“接口說明”,httpMethod = “接口請求方式”, response = “接口傳回參數類型”, notes = “接口釋出說明”；)
@ApiParam(required = “是否必須參數(true orfalse)”, name = “參數名稱”, value =“參數具體描述”)
最終界面
輸入相應值，點 Try it out! 進行測試
我這邊路徑是錯誤的，是以跳轉到我的404頁面，修改下路徑就好了。