## api文檔 Swagger - 前后端分離后的契約 ### 前后端分離 >按照現在的趨勢，前后端分離幾乎已經是業界對開發和部署方式所達成的一種共識。所謂的前后端分離，并不是傳統行業中的按部門劃分，一部分人只做前端（HTML/CSS/JavaScript等等），另一部分人只做后端（或者叫服務端），因為這種方式是不工作的：比如很多團隊采取了后端的模板技術（JSP, FreeMarker, ERB等等），前端的開發和調試需要一個后臺Web容器的支持，從而無法將前后端開發和部署做到真正的分離。 通常，前后端分別有著自己的開發流程，構建工具，測試等。做前端的誰也不會想要用Maven或者Gradle作為構建工具，同樣的道理，做后端的誰也不會想要用Grunt或者Gulp作為構建工具。前后端僅僅通過接口來協作，這個接口可能是JSON格式的RESTFul的接口，也可能是XML的，重點是后臺只負責數據的提供和計算，而完全不處理展現。而前端則負責拿到數據，組織數據并展現的工作。這樣結構清晰，關注點分離，前后端會變得相對獨立并松耦合。但是這種想法依然還是很理想化，前后端集成往往還是一個很頭痛的問題。比如在最后需要集成的時候，我們才發現最開始商量好的數據結構發生了變化，而且這種變化往往是在所難免的，這樣就會增加大量的集成時間。 歸根結底，還是前端或者后端感知到變化的時間周期太長，不能“及時協商，盡早解決”，最終導致集中爆發。怎么解決這個問題呢？我們需要提前協商好一些契約，并將這些契約作為可以被測試的中間產品，然后前后端都通過自動化測試來檢驗這些契約，一旦契約發生變化，測試就會失敗。這樣，每個失敗的測試都會驅動雙方再次協商，有效的縮短了反饋周期，并且降低集成風險。具體的實踐方式，請參加我同事的一篇博文，“前后端分離了，然后呢？”[http://icodeit.org/2015/06/whats-next-after-separate-frontend-and-backend/](http://icodeit.org/2015/06/whats-next-after-separate-frontend-and-backend/)。 不過，僅僅靠紀律是不夠的，還需要通過工具的輔助來提高效率。下面，我們就來看一下，一個API設計工具——Swagger，將如何幫助我們更好的實現“前后端分離”。 兩款更符合前后分離的swagger-ui [swagger-bootstrap-ui](https://gitee.com/xiaoym/swagger-bootstrap-ui) [swagger-mg-ui](https://gitee.com/zyplayer/swagger-mg-ui) 封裝swagger依賴，方便使用 pom核心依賴 ``` <dependencies> <!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-bean-validators</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.1</version> </dependency> <dependency> <groupId>com.zyplayer</groupId> <artifactId>swagger-mg-ui</artifactId> <version>${swagger.m.version}</version> </dependency> </dependencies> ``` 使用方法 ``` <!-- swagger --> <dependency> <groupId>com.open.capacity</groupId> <artifactId>swagger-core</artifactId> <version>${core.version}</version> </dependency> ``` ## SwaggerConfig 自動形成swagger文檔核心代碼 ``` package com.open.capacity.server.config; import org.springframework.context.MessageSource; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.support.ResourceBundleMessageSource; import org.springframework.stereotype.Component; import org.springframework.web.servlet.ViewResolver; import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import org.springframework.web.servlet.view.InternalResourceViewResolver; import org.springframework.web.servlet.view.JstlView; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.List; @Component @Configuration @EnableSwagger2 public class SwaggerConfig implements WebMvcConfigurer { @Bean public Docket createRestApi() { ParameterBuilder tokenPar = new ParameterBuilder(); List<Parameter> pars = new ArrayList<>(); tokenPar.name("Authorization").description("令牌"). modelRef(new ModelRef("string")). parameterType("header").required(false).build(); ParameterBuilder clientPar = new ParameterBuilder(); clientPar.name("client_id").description("應用ID"). modelRef(new ModelRef("string")). parameterType("header").required(false).build(); ParameterBuilder secretPar = new ParameterBuilder(); secretPar.name("client_secret").description("應用密鑰"). modelRef(new ModelRef("string")). parameterType("header").required(false).build(); pars.add(tokenPar.build()); pars.add(clientPar.build()); pars.add(secretPar.build()); return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // .apis(RequestHandlerSelectors.basePackage("com.open.capacity")) .apis(RequestHandlerSelectors.any()) .paths( input -> PathSelectors.regex("/oauth/client.*").apply(input) || PathSelectors.regex("/oauth/user.*").apply(input) || PathSelectors.regex("/oauth/get.*").apply(input) || PathSelectors.regex("/oauth/userinfo.*").apply(input) || PathSelectors.regex("/oauth/remove.*").apply(input) || PathSelectors.regex("/oauth/refresh/token.*").apply(input)|| PathSelectors.regex("/oauth/token/list.*").apply(input)|| PathSelectors.regex("/clients.*").apply(input)|| PathSelectors.regex("/services.*").apply(input)|| PathSelectors.regex("/redis.*").apply(input) ) // .paths(PathSelectors.any()) .build().globalOperationParameters(pars); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("認證中心swagger接口文檔").description("認證中心swagger接口文檔").version("1.0").build(); } @Bean public ViewResolver viewResolver() { InternalResourceViewResolver resolver = new InternalResourceViewResolver(); resolver.setViewClass(JstlView.class); resolver.setPrefix("/"); resolver.setSuffix(".html"); return resolver; } @Bean public MessageSource messageSource() { ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource(); messageSource.setBasename("messages"); return messageSource; } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // super.addResourceHandlers(registry); registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } @Override public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) { configurer.enable(); } } ``` ## 訪問網關swagger-ui [http://106.13.3.200:9200/swagger-ui.html](http://106.13.3.200:9200/swagger-ui.html)  ## 訪問認證中心swagger-ui [http://106.13.3.200:8000/doc.html](http://106.13.3.200:8000/doc.html)   ## 訪問用戶中心swagger-ui