swagger的簡單了解

什么是 Swagger?

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

什么是 Swagger?

Swagger™的目標是為REST APIs 定義一個標准的，與語言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下能發現和理解各種服務的功能。當服務通過Swagger定義，消費者就能與遠程的服務互動通過少量的實現邏輯。類似於低級編程接口，Swagger去掉了調用服務時的很多猜測。 
瀏覽 Swagger-Spec 去了解更多關於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-springmvc項目並且使用默認設置，推薦的方式是使用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;
}
}

二、碰到的問題

關於@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<HelloWorldConfiguration> bootstrap) {
    //指定配置文件的名字
    bootstrap.setName("helloWorld");
    bootstrap.addBundle(new AssetsBundle("/assets", "/", "index.html"));
}

 

最后的效果圖： 

 

 

三、評價

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

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

四、參考資料

官網：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

教程：http://how2j.cn?p=35025