Swagger入門教程

前言

Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。本文簡單介紹了在項目中集成swagger的方法和一些常見問題。如果想深入分析項目源碼，了解更多內容，見參考資料。

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件係統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。
一、使用介紹

什麼是 Swagger?

Swagger™的目標是為REST APIs 定義一個標準的，與語言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下能發現和理解各種服務的功能。當服務通過Swagger定義，消費者就能與遠程的服務互動通過少量的實現邏輯。類似於低級編程接口，Swagger去掉了調用服務時的很多猜測。
瀏覽 Swagger-Spec 去了解更多關於Swagger 項目的信息，包括附加的支持其他語言的庫。

如何集成Swagger-springmvc到我們的項目中?

依賴：
Maven

com.mangofactory
swagger-springmvc
0.9.4

Gradle

repositories {
jcenter()
}

compile "com.mangofactory:swagger-springmvc:0.9.4"
使用：
要最快捷地啟動swagger-springmvc項目並且使用默認設置，推薦的方式是使用SwaggerSpringMvc插件

Spring Java Configuration

@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan("com.myapp.packages")
public class WebAppConfig {
...
}
Spring xml Configuration

mvc:annotation-driven/ 

SwaggerSpringMvcPlugin XML Configuration

為了使用這個插件，你需要創造一個spring java配置類。使用spring的 @Configuration ，這個配置類必須被定義到你的xml上下文

mvc:annotation-driven/

@Configuration
@EnableSwagger //Loads the spring beans required by the framework
public class MySwaggerConfig {

private SpringSwaggerConfig springSwaggerConfig;

/**

Required to autowire SpringSwaggerConfig */ @Autowired public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) { this.springSwaggerConfig = springSwaggerConfig; }

/**

Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc framework - allowing for multiple
swagger groups i.e. same code base multiple swagger resource listings. / @Bean public SwaggerSpringMvcPlugin customImplementation(){ return new SwaggerSpringMvcPlugin(this.springSwaggerConfig) .includePatterns(".*pet."); }

}
SwaggerSpringMvcPlugin Spring Java Configuration

使用@EnableSwagger注解
自動注入SpringSwaggerConfig
定義一個或多個SwaggerSpringMvcPlugin實例，通過springs @Bean注解

@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan("com.myapp.controllers")
public class CustomJavaPluginConfig {

private SpringSwaggerConfig springSwaggerConfig;

@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}

@Bean //Don't forget the @Bean annotation
public SwaggerSpringMvcPlugin customImplementation(){
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*pet.*");
}

private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo(
"My Apps API Title",
"My Apps API Description",
"My Apps API terms of service",
"My Apps API Contact Email",
"My Apps API Licence Type",
"My Apps API License URL"
);
return apiInfo;
}
}
二、碰到的問題

關於@API注解

在Swagger Annotation中：
API表示一個開放的API，可以通過description簡要描述該API的功能。
在一個@API下，可有多個@ApiOperation，表示針對該API的CRUD操作。在ApiOperation Annotation中可以通過value，notes描述該操作的作用，response描述正常情況下該請求的返回對象類型。
在一個ApiOperation下，可以通過ApiResponses描述該API操作可能出現的異常情況。
ApiParam用於描述該API操作接受的參數類型
再接著，為項目的Model對象添加Swagger Annotation，這樣Swagger Scanner可以獲取更多關於Model對象的信息。
@ApiModel(value = "A SayingRepresentation is a representation of greeting")
@JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
public class SayingRepresentation {
private long id;
@ApiModelProperty(value = "greeting content", required = true)
private String content;

public SayingRepresentation(long id, String content) {
this.id = id;
this.content = content;
}

public long getId() {
return id;
}

public String getContent() {
return content;
}
通過上麵的步驟，項目已經具備了提供Swagger格式的API信息的能力，接下來，我們把這些信息和Swagger UI集成，以非常美觀，實用的方式把這些API信息展示出來。

和Swagger UI的集成

首先，從github(https://github.com/wordnik/swagger-ui)上下載Swagger-UI, 把該項目dist目錄下的內容拷貝到項目的resources的目錄assets下。

然後，修改index.html, 把Swagger UI對象中的URL替換為自己的API路徑。

window.swaggerUi = new SwaggerUi({
url: "/api/api-docs",
dom_id: "swagger-ui-container",
最後，為了能訪問到該頁麵，還需要在Service的Initialize方法中，添加AssetsBundle

public void initialize(Bootstrap bootstrap) {
//指定配置文件的名字
bootstrap.setName("helloWorld");
bootstrap.addBundle(new AssetsBundle("/assets", "/", "index.html"));
}
最後的效果圖：

三、評價

Swagger可以充當前後端交流的重要橋梁，方便快捷。很實用。

Swagger項目允許你生產，顯示和消費你自己的RESTful服務。不需要代理和第三方服務。是一個依賴自由的資源集合，它能通過Swagger API動態的生成漂亮的文檔和沙盒,因為Swagger UI沒有依賴，你可以把他部署到任何服務器環境或者是你自己的機器。

四、參考資料

官網：https://swagger.io/

GitHub：
swagger-springmvc:https://github.com/martypitt/swagger-springmvc

swagger-ui:https://github.com/swagger-api/swagger-ui

swagger-core:https://github.com/swagger-api/swagger-core

swagger-spec：https://github.com/swagger-api/swagger-spec

最後更新：2017-09-07 21:02:27