如今，公開的API終于獲得了應(yīng)有的關(guān)注，公司也開始意識(shí)到其戰(zhàn)略價(jià)值。 但是，使用第三方API確實(shí)是一項(xiàng)繁瑣的工作，尤其是當(dāng)這些API維護(hù)不當(dāng)，設(shè)計(jì)不當(dāng)或缺少任何文檔時(shí)。 這就是為什么我決定四處尋找可以為集成編程人員和其他團(tuán)隊(duì)成員提供適當(dāng)文檔的方法的原因。 一種方式是使用WADL，WADL是專門設(shè)計(jì)用于描述基于HTTP的Web應(yīng)用程序（如REST Web服務(wù)）的標(biāo)準(zhǔn)。 但是，使用WADL時(shí)幾乎沒有什么缺點(diǎn)，這使我無法在其他地方尋找如何正確記錄和公開API文檔的解決方案。

昂首闊步

另一種方法可能是與Swagger一起使用。 Swagger是規(guī)范和框架實(shí)現(xiàn)，均支持RESTful Web服務(wù)開發(fā)的整個(gè)生命周期。 規(guī)范本身是與語言無關(guān)的，在異構(gòu)環(huán)境中可能會(huì)派上用場(chǎng)。 Swagger還帶有Swagger UI模塊，該模塊允許程序員和其他團(tuán)隊(duì)成員與API進(jìn)行有意義的交互，并為他們提供了一種使用它的方式，同時(shí)提供了對(duì)文檔的訪問權(quán)限。

Spring with Jersey示例

不久前，我遇到了一篇描述Swagger規(guī)范的文章，我很感興趣嘗試一下。 那時(shí)，我正在開發(fā)一種不錯(cuò)的微服務(wù)，因此我有一個(gè)理想的測(cè)試場(chǎng)來進(jìn)行嘗試。 基于此，我準(zhǔn)備了一個(gè)簡(jiǎn)短的示例，說明了在使用Spring框架和Jersey時(shí)如何在應(yīng)用程序中使用Swagger。 示例代碼模型簡(jiǎn)化了商店應(yīng)用程序場(chǎng)景中可能的API子集的REST API。

注意：所有Java代碼示例均省略了導(dǎo)入聲明。

澤西小服務(wù)程序

在開始將Swagger引入我們的代碼之前，讓我們花點(diǎn)時(shí)間來探討一下我們的示例。 首先，讓我們看一下web.xml 。 下面的代碼示例中有簡(jiǎn)單的舊web.xml ，幾乎沒有簡(jiǎn)單的聲明和映射。 這里沒什么特別的，只是一堆配置。

<web-app id="SpringWithSwagger" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"><display-name>Spring Jersey Swagger Example</display-name><context-param><param-name>contextConfigLocation</param-name><param-value>classpath:beans.xml</param-value></context-param><listener><listener-class>org.springframework.web.context.ContextLoaderListener</listener-class></listener><servlet><servlet-name>jersey-serlvet</servlet-name><servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class><init-param><param-name>javax.ws.rs.Application</param-name><param-value>com.jakubstas.swagger.SpringWithSwagger</param-value></init-param><load-on-startup>1</load-on-startup></servlet><servlet-mapping><servlet-name>jersey-serlvet</servlet-name><url-pattern>/rest/*</url-pattern></servlet-mapping> </web-app>

終點(diǎn)

我們需要的第二件事是定義我們的REST服務(wù)的端點(diǎn)-例如用于列出當(dāng)前雇員的雇員端點(diǎn)。 再一次，沒有什么特別的，只有少數(shù)提供核心API功能的公開方法。

package com.jakubstas.swagger.rest;@Path("/employees") public class EmployeeEndpoint {private List<Employee> employees = new ArrayList<Employee>();{final Employee employee = new Employee();employee.setEmployeeNumber(1);employee.setFirstName("Jakub");employee.setSurname("Stas");employees.add(employee);}@OPTIONSpublic Response getProductsOptions() {final String header = HttpHeaders.ALLOW;final String value = Joiner.on(", ").join(RequestMethod.GET, RequestMethod.OPTIONS).toString();return Response.noContent().header(header, value).build();}@GET@Produces(MediaType.APPLICATION_JSON)public Response getEmployees() {return Response.ok(employees).build();} }

昂首闊步的依賴

我們要做的第一件事是在pom.xml包含所有必需的Swagger依賴項(xiàng)，如下所示（幸運(yùn)的是，這只是一個(gè)依賴項(xiàng)）。

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">...<properties>...<swagger-version>1.3.8</swagger-version>...</properties>...<dependencies> ...<!-- Swagger --><dependency><groupId>com.wordnik</groupId><artifactId>swagger-jersey2-jaxrs_2.10</artifactId><version>${swagger-version}</version></dependency>...</dependencies> </project>

昂首闊步的配置

現(xiàn)在，讓我們看一下Swagger如何集成到我們的示例中。 與在項(xiàng)目中引入任何新依賴項(xiàng)一樣，您應(yīng)該關(guān)注此過程的侵入性和成本。 受影響的唯一地方將是您的REST端點(diǎn)，Spring配置和一些傳輸對(duì)象（假設(shè)您選擇包括它們），如以下代碼示例中所示。 這意味著Swagger不需要在web.xml進(jìn)行配置即可與您的Spring應(yīng)用程序一起使用，這意味著它以這種方式是非侵入性的，并且仍受API領(lǐng)域的限制。

您需要Swagger才能使用三個(gè)基本屬性：

• API版本
  • 提供應(yīng)用程序API的版本
• 基本路徑
  • 提供API的根URL
• 資源包
  • 定義在哪里尋找Swagger注釋的包

由于API維護(hù)主要由分析人員和程序員負(fù)責(zé)，因此我希望將此配置保存在名為swagger.properties的單獨(dú)屬性文件中。 這樣，它就不會(huì)與應(yīng)用程序配置混合在一起，并且不太可能被意外修改。 以下片段描述了這樣的配置文件。

swagger.apiVersion=1.0 swagger.basePath=http://[hostname/ip address]:[port]/SpringWithSwagger/rest swagger.resourcePackage=com.jakubstas.swagger.rest

對(duì)于配置的第二部分，我利用前面提到的屬性創(chuàng)建了一個(gè)配置bean。 使用Spring的@PostConstruct批注提供bean生命周期掛鉤，我們可以實(shí)例化和設(shè)置Swagger所需的某些屬性，但不能獲取（至少在當(dāng)前版本中）。

package com.jakubstas.swagger.rest.config;/*** Configuration bean to set up Swagger.*/ @Component public class SwaggerConfiguration {@Value("${swagger.resourcePackage}")private String resourcePackage;@Value("${swagger.basePath}")private String basePath;@Value("${swagger.apiVersion}")private String apiVersion;@PostConstructpublic void init() {final ReflectiveJaxrsScanner scanner = new ReflectiveJaxrsScanner();scanner.setResourcePackage(resourcePackage);ScannerFactory.setScanner(scanner);ClassReaders.setReader(new DefaultJaxrsApiReader());final SwaggerConfig config = ConfigFactory.config();config.setApiVersion(apiVersion);config.setBasePath(basePath);}public String getResourcePackage() {return resourcePackage;}public void setResourcePackage(String resourcePackage) {this.resourcePackage = resourcePackage;}public String getBasePath() {return basePath;}public void setBasePath(String basePath) {this.basePath = basePath;}public String getApiVersion() {return apiVersion;}public void setApiVersion(String apiVersion) {this.apiVersion = apiVersion;} }

最后一步是聲明以下三個(gè)Swagger bean： ApiListingResourceJSON ， ApiDeclarationProvider和ResourceListingProvider 。

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"><context:component-scan base-package="com.jakubstas.swagger" /><context:property-placeholder location="classpath:swagger.properties" /><bean class="com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON" /><bean class="com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider" /><bean class="com.wordnik.swagger.jaxrs.listing.ResourceListingProvider" /> </beans>

現(xiàn)已配置Swagger，您可以檢查設(shè)置是否正常運(yùn)行。 只需從basePath變量中輸入U(xiǎn)RL，然后在瀏覽器中輸入/api-docs并檢查結(jié)果即可。 在我的示例中，您應(yīng)該看到類似于訪問http://[hostname]:[port]/SpringWithSwagger/rest/api-docs/后收到的以下代碼片段的輸出。

{"apiVersion":"1.0","swaggerVersion":"1.2"}

下一步是什么？

如果執(zhí)行了所有步驟，則現(xiàn)在應(yīng)該可以使用API??文檔開始進(jìn)行設(shè)置。 在我的下一篇名為Swagger的Spring Rest API –創(chuàng)建文檔中，我將展示如何使用Swagger注釋描述API。 該微型系列中使用的代碼在GitHub上發(fā)布，并提供了所有討論的功能和工具的示例。 請(qǐng)享受！

翻譯自: https://www.javacodegeeks.com/2014/10/spring-rest-api-with-swagger-integration-and-configuration.html

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎(jiǎng)勵(lì)來咯，堅(jiān)持創(chuàng)作打卡瓜分現(xiàn)金大獎(jiǎng)

總結(jié)

以上是生活随笔為你收集整理的带有Swagger的Spring Rest API –集成和配置的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。