Swagger 是一款RESTFUL接口的文檔在線自動(dòng)生成+功能測(cè)試功能軟件。本文簡(jiǎn)單介紹了在項(xiàng)目中集成swagger的方法和一些常見(jiàn)問(wèn)題。 如果想深入分析項(xiàng)目源碼临扮，了解更多內(nèi)容，見(jiàn)參考資料。Swagger 是一個(gè)規(guī)范和完整的框架佩番，用于生成、描述罢杉、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)趟畏。總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來(lái)更新滩租。文件的方法赋秀，參數(shù)和模型緊密集成到服務(wù)器端的代碼利朵，允許API來(lái)始終保持同步。Swagger 讓部署管理和使用功能強(qiáng)大的API從未如此簡(jiǎn)單沃琅。

歡迎訪問(wèn)本人博客：http://wangnan.tech

使用介紹

什么是swagger

Swagger?的目標(biāo)是為REST APIs 定義一個(gè)標(biāo)準(zhǔn)的哗咆，與語(yǔ)言無(wú)關(guān)的接口，使人和計(jì)算機(jī)在看不到源碼或者看不到文檔或者不能通過(guò)網(wǎng)絡(luò)流量檢測(cè)的情況下能發(fā)現(xiàn)和理解各種服務(wù)的功能益眉。當(dāng)服務(wù)通過(guò)Swagger定義晌柬，消費(fèi)者就能與遠(yuǎn)程的服務(wù)互動(dòng)通過(guò)少量的實(shí)現(xiàn)邏輯。類似于低級(jí)編程接口郭脂，Swagger去掉了調(diào)用服務(wù)時(shí)的很多猜測(cè)年碘。 瀏覽 Swagger-Spec 去了解更多關(guān)于Swagger 項(xiàng)目的信息，包括附加的支持其他語(yǔ)言的庫(kù)展鸡。

如何集成Swagger-springmvc到我們的項(xiàng)目中?

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"

要最快捷地啟動(dòng)swagger-springmvc項(xiàng)目并且使用默認(rèn)設(shè)置屿衅，推薦的方式是使用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

為了使用這個(gè)插件，你需要?jiǎng)?chuàng)造一個(gè)spring Java配置類莹弊。使用spring的 @Configuration 涤久，這個(gè)配置類必須被定義到你的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注解
自動(dòng)注入SpringSwaggerConfig
定義一個(gè)或多個(gè)SwaggerSpringMvcPlugin實(shí)例，通過(guò)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;
}
}

碰到的問(wèn)題

關(guān)于@API注解

在Swagger Annotation中：

API表示一個(gè)開(kāi)放的API忍弛，可以通過(guò)description簡(jiǎn)要描述該API的功能响迂。
在一個(gè)@API下，可有多個(gè)@ApiOperation细疚，表示針對(duì)該API的CRUD操作蔗彤。在ApiOperation Annotation中可以通過(guò)value，notes描述該操作的作用疯兼，response描述正常情況下該請(qǐng)求的返回對(duì)象類型然遏。 在一個(gè)ApiOperation下，可以通過(guò)ApiResponses描述該API操作可能出現(xiàn)的異常情況吧彪。

ApiParam用于描述該API操作接受的參數(shù)類型
再接著待侵，為項(xiàng)目的Model對(duì)象添加Swagger Annotation，這樣Swagger Scanner可以獲取更多關(guān)于Model對(duì)象的信息姨裸。

@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;
}

通過(guò)上面的步驟诫给，項(xiàng)目已經(jīng)具備了提供Swagger格式的API信息的能力，接下來(lái)啦扬，我們把這些信息和Swagger UI集成中狂，以非常美觀，實(shí)用的方式把這些API信息展示出來(lái)扑毡。

和Swagger UI的集成

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

然后，修改index.html, 把Swagger UI對(duì)象中的URL替換為自己的API路徑勋又。

  window.swaggerUi = new SwaggerUi({
  url: "/api/api-docs",
  dom_id: "swagger-ui-container",

最后苦掘，為了能訪問(wèn)到該頁(yè)面，還需要在Service的Initialize方法中楔壤，添加AssetsBundle

public void initialize(Bootstrap<HelloWorldConfiguration> bootstrap) {
    //指定配置文件的名字
    bootstrap.setName("helloWorld");
    bootstrap.addBundle(new AssetsBundle("/assets", "/", "index.html"));
}

最后的效果圖：

評(píng)價(jià)

Swagger可以充當(dāng)前后端交流的重要橋梁鹤啡，方便快捷。很實(shí)用蹲嚣。

Swagger項(xiàng)目允許你生產(chǎn)递瑰，顯示和消費(fèi)你自己的RESTful服務(wù)。不需要代理和第三方服務(wù)隙畜。是一個(gè)依賴自由的資源集合抖部，它能通過(guò)Swagger API動(dòng)態(tài)的生成漂亮的文檔和沙盒,因?yàn)镾wagger UI沒(méi)有依賴，你可以把他部署到任何服務(wù)器環(huán)境或者是你自己的機(jī)器议惰。

參考資料

官網(wǎng)：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