一、什么是 Swagger?
Swagger 是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。
Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。
Swagger 能夠使文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。
Swagger 通過Swagger API動態生成漂亮的文檔和沙盒, 沒有依賴，可以部署到任何服務器環境。
Swagger 的目標是為REST APIs 定義一個標准的，與語言無關的接口，
使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下能發現和理解各種服務的功能。
當服務通過Swagger定義，消費者就能與遠程的服務互動通過少量的實現邏輯。
二、集成Swagger-springmvc
依賴：
Maven
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.9.4</version>
</dependency>
Gradle
repositories {
jcenter()
}
compile "com.mangofactory:swagger-springmvc:0.9.4"
三、使用Swagger
1、使用SwaggerSpringMvc插件
Spring Java Configuration
@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan("com.myapp.packages")
public class WebAppConfig {
...
}
Spring xml Configuration
<mvc:annotation-driven/> <!-- Required so swagger-springmvc can access spring's RequestMappingHandlerMapping -->
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
SwaggerSpringMvcPlugin XML Configuration
為了使用這個插件，你需要創造一個spring java配置類。使用spring的 @Configuration ，這個配置類必須被定義到你的xml上下文
<!-- Required so swagger-springmvc can access spring's RequestMappingHandlerMapping -->
<mvc:annotation-driven/>
<bean class="com.yourapp.configuration.MySwaggerConfig"/>
@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;
}
}
2、關於@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信息展示出來。
3、和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<HelloWorldConfiguration> bootstrap) {
//指定配置文件的名字
bootstrap.setName("helloWorld");
bootstrap.addBundle(new AssetsBundle("/assets", "/", "index.html"));
}
最后的效果圖：
四、參考資料
官網：http://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