Swagger 這一個文章就夠了

# Swagger 這一個文章就夠了 From：https://blog.csdn.net/crisschan ## Swagger快速理解 Swagger:The Best APIs are Built with Swagger Tools 。Swagger可以定義一個標准的RESTful風格的API，與語言無關，是一個API的規范。 Swagger官網：http://swagger.io GitHub地址：https://github.com/swagger-api 這里，提到Swagger就不得不說說Springfox,Springfox是一個開源的API Doc的框架， 它的前身是swagger-springmvc，可以將我們的Controller中的方法以文檔的形式展現。官方定義為： Automated JSON API documentation for API's built with Spring。Swagger和SpringFox到底什么關系呢？ - Swagger Spec 是一個規范。 - Swagger Api 是 Swagger Spec 規范 的一個實現，它支持 jax-rs, restlet, jersey 等等。 - Springfox libraries 是 Swagger Spec 規范 的另一個實現，專注於 spring 生態系統。 - Swagger.js and Swagger-ui 是 javascript 的客戶端庫，能消費該規范。 - springfox-swagger-ui 僅僅是以一種方便的方式封裝了 swagger-ui ，使得 Spring 服務可以提供服務。 在官網的Tools菜單中，我們會方法里面有很多工具或者系統的介紹。其中我們最常用的兩個工具一個是swagger editor、一個是swagger UI。 ## Swagger Edit Swagger Edit主要是用來設計，描述API的工具，主要是提供給接口開發人員使用的。swagger editor 編譯完接口文檔之后呢，會形成一個文件。 ## Swagger UI Swagger UI允許任何人 - 無論是您的開發團隊還是最終消費者 - 在沒有任何實現邏輯的情況下可視化和與API資源交互。 它是從您的OpenAPI規范自動生成的，其可視化文檔使后端實現和客戶端消費變得容易。 swagger-editor主要是編寫api接口文檔，但需要配合swagger-ui來查看，里面的代碼格式為yaml，但編輯后可以導出yml/json文件 ## Swagger Edit和Swagger UI 互補性存在 如果只是手動寫api文檔，人工查看那么就做部署Swagger Edit和Swagger UI就可以了。 ### 通過下面命令下載兩個項目： mkdir swagger chmod 777 swagger cd swagger git clone https://github.com/swagger-api/swagger-editor.git git clone https://github.com/swagger-api/swagger-ui.git PS: UI和Edit都是NodeJS的開發，一次需要先安裝Nodejs的運行環境。 下載nodejs的安裝包，具體要去網站上查看最新版本 wget https://nodejs.org/dist/v6.11.3/node-v6.11.3.tar.gz tar -zxvf node-v6.11.3.tar.gz mv node-v6.11.3 /user/local/node cd /usr/local/node ./configure make make install node -v ### 先安裝http-server npm install -g http-server -g表示全局 ### 啟動ui和edit http-server –p 12321 swagger-editor http-server –p 12421 swagger-ui cd swagger-ui/dist vim index.html 進入index.html后，修改如下字段 ... const ui = SwaggerUIBundle({ //url: "http://petstore.swagger.io/v2/swagger.json", url: "http://127.0.0.1:12321/json/1.json", dom_id: '#swagger-ui', ... 然后保存后 打開瀏覽器： swaggerEdit ： http://127.0.0.1：12321 swaggerUI：http://127.0.0.1：12421/dist ## Maven插件在原生工程里面快速生產Json的api文件（轉自：https://blog.csdn.net/doctor_who2004/article/details/50816208） 在maven工程的pom文件中，放入如下插件： org.apache.maven.plugins maven-javadoc-plugin UTF-8 UTF-8 false com.github.kongchen swagger-maven-plugin false com.doctor.demo http,https petstore.swagger.wordnik.com /api v1 This is a sample for swagger-maven-plugin http://www.github.com/kongchen/swagger-maven-plugin [e-mail] Kong Chen http://kongch.com http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 Support classpath or file absolute path here. 1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html" 2) file e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/template/hello.html" ${basedir}/templates/strapdown.html.hbs ${basedir}/generated/document.html generated/swagger-ui compile generate ## Swagger和SpringMVC項目的整合（轉自：https://www.cnblogs.com/jtlgb/p/6734177.html） ### 引入依賴 com.mangofactory swagger-springmvc 1.0.2 com.mangofactory swagger-models 1.0.2 com.wordnik swagger-annotations 1.3.11 com.google.guava guava 15.0 com.fasterxml.jackson.core jackson-annotations 2.4.4 com.fasterxml.jackson.core jackson-databind 2.4.4 com.fasterxml.jackson.core jackson-core 2.4.4 com.fasterxml classmate 1.1.0 ## Swagger配置 Swagger的配置實際上就是自定義一個Config類，通過java編碼的方式實現配置。代碼如下： import com.mangofactory.swagger.configuration.SpringSwaggerConfig; import com.mangofactory.swagger.models.dto.ApiInfo; import com.mangofactory.swagger.plugin.EnableSwagger; import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; /** * Created by xiaohui on 2016/1/14. */ @Configuration @EnableSwagger @EnableWebMvc public class SwaggerConfig { 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) .apiInfo(apiInfo()) .includePatterns(".*?"); } 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; } } 在springmvc的配置文件中加入以下配置即可。   到目前為止，我們已經完成了對所有接口方法的掃描解析功能，那解析得到什么內容呢？這需要我們自定義，自定義操作的對象就是接口方法。先看段代碼： /** * 根據用戶名獲取用戶對象 * @param name * @return */ @RequestMapping(value="/name/{name}", method = RequestMethod.GET) @ResponseBody @ApiOperation(value = "根據用戶名獲取用戶對象", httpMethod = "GET", response = ApiResult.class, notes = "根據用戶名獲取用戶對象") public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用戶名") @PathVariable String name) throws Exception{ UcUser ucUser = ucUserManager.getUserByName(name); if(ucUser != null) { ApiResult result = new ApiResult (); result.setCode(ResultCode.SUCCESS.getCode()); result.setData(ucUser); return result; } else { throw new BusinessException("根據{name=" + name + "}獲取不到UcUser對象"); } } 上述代碼是Controller中的一個方法，@ApiOperation注解對這個方法進行了說明，@ApiParam注解對方法參數進行了說明。關於這兩個注解的使用，可以參看源碼。這樣子，Swagger就可以掃描接口方法，得到我們自定義的接口說明內容。 說明： 其中@ApiOperation和@ApiParam為添加的API相關注解，個參數說明如下： @ApiOperation(value = “接口說明”, httpMethod = “接口請求方式”, response = “接口返回參數類型”, notes = “接口發布說明”；其他參數可參考源碼； @ApiParam(required = “是否必須參數”, name = “參數名稱”, value = “參數具體描述” ### Swagger-UI配置 Swagger掃描解析得到的是一個json文檔，對於用戶不太友好。下面介紹swagger-ui，它能夠友好的展示解析得到的接口說明內容。 從https://github.com/swagger-api/swagger-ui 獲取3.0版本以下，2.0版本以上。其所有的 dist 目錄下東西放到需要集成的項目里，本文放入 src/main/webapp/WEB-INF/swagger/ 目錄下。 修改swagger/index.html文件，默認是從連接http://petstore.swagger.io/v2/swagger.json獲取 API 的 JSON，這里需要將url值修改為http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根據自身情況填寫。比如我的url值為：http://localhost:8083/arrow-api/api-docs 因為swagger-ui項目都是靜態資源，restful形式的攔截方法會將靜態資源進行攔截處理，所以在springmvc配置文件中需要配置對靜態文件的處理方式。 //所有swagger目錄的訪問，直接訪問location指定的目錄  OK！大功告成，打開瀏覽器直接訪問swagger目錄下的index.html文件，即可看到接口文檔說明了 ## 參考： https://blog.csdn.net/kinginblue/article/details/78513029 https://www.jianshu.com/p/52acab692a79 https://blog.csdn.net/doctor_who2004/article/details/50816208 https://www.cnblogs.com/jtlgb/p/6734177.html 關注我，關注測試 **From：https://blog.csdn.net/crisschan**