(一)Swagger和SpringFox
記錄REST API非常重要。它是一個公共接口，其他模塊，應用程序或開發人員可以使用它。即使你沒有公開曝光它，它仍然很重要。后端和前端代碼通常由不同的開發人員處理。創建API的人通常不是消費它的人。因此，擁有適當記錄的界面以避免混淆並使其始終保持最新是至關重要的。
最受歡迎的API文檔規范之一是OpenApi，以前稱為Swagger。它允許您使用JSON或YAML元數據描述API的屬性。它還提供了一個Web UI，它可以將元數據轉換為一個很好的HTML文檔。此外，通過該UI，您不僅可以瀏覽有關API端點的信息，還可以將UI用作REST客戶端 - 您可以調用任何端點，指定要發送的數據並檢查響應。它非常方便。
然而，手動編寫此類文檔並在代碼更改時保持更新是不現實的。這就是SpringFox發揮作用的地方。它是Spring Framework的Swagger集成。它可以自動檢查您的類，檢測控制器，它們的方法，它們使用的模型類以及它們映射到的URL。沒有任何手寫文檔，只需檢查應用程序中的類，它就可以生成大量有關API的信息。多么酷啊？最重要的是，每當您進行更改時，它們都會反映在文檔中。
(二)開始項目
首先，你需要一個帶有一些Rest Controller的Spring Boot應用程序，我在這里准備了一個簡單的。
在本文中，我使用了SpringFox 2.9.2和Spring Boot 1.5.10.RELEASE。它使用Swagger規范的第2版。版本3已經發布，但尚未（截至2014年2月）SpringFox支持。支持應在下一版本中提供。
使用本博文中描述的所有功能構建的最終項目的源代碼可在GitHub上獲得。
(三)添加依賴項
要在項目中使用SpringFox，您需要先將其添加為依賴項。如果您使用的是Maven，則可以使用以下內容（您可以檢查是否有更新的版本）。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
或者如果您使用的是Gradle：
compile "io.springfox:springfox-swagger2:2.9.2"
(四)基本配置
添加依賴項后，您需要提供一些基本的Spring配置。雖然您可以在技術上使用現有配置文件之一，但最好為其配置單獨的文件。您需要提供的第一件事是@ EnableSwagger2注釋。然后你需要提供一個Docket bean，它是用於配置SpringFox的主bean。
@Configuration @EnableSwagger2 public class SpringFoxConfig { @Bean public Docket apiDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } }
當然，您可以提供更多配置設置，我們稍后會看到，但這是一個簡約配置，它執行以下操作：
- @ EnableSwagger2支持Swagger 2的SpringFox支持。
- DocumentationType.SWAGGER_2告訴Docket bean我們正在使用Swagger規范的版本2。
- select（）創建一個構建器，用於定義哪些控制器及其生成的文檔中應包含哪些方法。
- apis（）定義要包含的類（控制器和模型類）。這里我們包括所有這些，但您可以通過基礎包，類注釋等來限制它們。
- paths（）允許您根據路徑映射定義應包含哪個控制器的方法。我們現在包括所有這些，但您可以使用正則表達式等限制它。
(五)添加UI
如果您現在部署應用程序，則已經生成了描述API的swagger元數據！你可以看看：
http://localhost:8080/v2/api-docs
事實證明它只是一個很大的JSON，而不是人類可讀的。但你已經可以驗證它是否有效。只需轉到Swagger在線編輯器並將JSON粘貼到那里。將生成的JSON粘貼到左側面板，瞧！您現在可以將生成的文檔視為HTML頁面。不錯，不是嗎？將這些文檔作為應用程序的一部分直接使用會更好。幸運的是，實現這一點非常容易。顯示基於JSON輸入的HTML文檔的GUI稱為swagger-ui。要啟用它是一個Spring Boot應用程序，您只需要添加此依賴項：
//MAVEN <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> //GRADLE compile "io.springfox:springfox-swagger-ui:2.9.2"
該文檔將在此處自動提供：
http://localhost:8080/swagger-ui.html
(六)添加ApiInfo
默認情況下，我們文檔的標題部分看起來非常通用：
現在是時候做點什么了。我們可以通過簡單的配置更改來更改那里的所有信息。在SpringFoxConfiguration文件中，我們需要添加ApiInfo對象，該對象提供有關API的一般信息，例如標題，版本，聯系人或許可信息。
@Bean public Docket apiDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() .apiInfo(getApiInfo()); } private ApiInfo getApiInfo() { return new ApiInfo( "TITLE", "DESCIPRION", "VERSION", "TERMS OF SERVICE URL", new Contact("NAME","URL","EMAIL"), "LICENSE", "LICENSE URL", Collections.emptyList() ); }
現在我們的文檔標題應該看起來更好：
(七)縮小已處理的API
到現在為止還挺好。但是當你仔細看看生成的文檔時，你會發現除了我們使用的模型和控制器類之外，還有一些特定於Spring的類，如Controllers部分中的BasicErrorController以及View和ModelAndView下的型號部分。
有時，縮小類，SpringFox會將其檢測為文檔生成源。Controller和Model類。您可以在Docket配置中輕松配置它。還記得像我們使用.apis（RequestHandlerSelectors.any（）來包含所有類嗎？讓我們將它縮小到我們的基礎包：
@Bean public Docket apiDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.vojtechruzicka")) .paths(PathSelectors.any()) .build() .apiInfo(getApiInfo()); }
當您想要指定應包含哪些類時，這非常有用。有時您還需要只包含特定的URL路徑。您可能正在使用API的多個版本以實現向后兼容，但不希望包含歷史版本。也許API的某些部分是內部的，不應該是公共文檔的一部分。無論哪種方式，也可以在Docket中配置基於URL匹配的這種包含。記住.paths（PathSelectors.any（））？您可以將其限制為某些正則表達式或Ant樣式的路徑模式，而不是匹配所有路徑的任何路徑。
@Bean public Docket apiDocket() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.vojtechruzicka")) .paths(PathSelectors.ant("/v2/**")) .build() .apiInfo(getApiInfo()); }
如果內置選項對您來說還不夠，您可以隨時為apis（）和paths（）提供自己的謂詞。忽略某些類或方法的另一種方法是使用@ApiIgnore注釋它們。
(八)使用JSR-303注解
JSR 303：Bean Validation 允許您注釋Java類的字段以聲明約束和驗證規則。您可以使用以下規則注釋單個字段： - 不能為空，最小值，最大值，正則表達式匹配等。
public class Person { @NotNull private int id; @NotBlank @Size(min = 1, max = 20) private String firstName; @NotBlank @Pattern(regexp ="[SOME REGULAR EXPRESSION]") private String lastName; @Min(0) @Max(100) private int age; //... Constructor, getters, setters, ... }
這是一種已經廣泛使用的常見做法。好消息是，SpringFox可以根據這些注釋生成Swagger文檔，因此您可以利用項目中已有的內容而無需手動編寫所有約束！它非常有用，因為您的API的消費者知道他們應該為您的API提供的值的限制以及期望的值。如果沒有包含這樣的注釋，我們的人員模型的生成文檔看起來很簡單，除了字段名稱及其數據類型之外什么也沒有。
使用來自JSR-303注釋的數據，它看起來會更好：
不幸的是，基於JSR-303的文檔無法開箱即用，您需要一個額外的依賴：
//MAVEN <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-bean-validators</artifactId> <version>2.9.2</version> </dependency> //GRADLE compile "io.springfox:springfox-bean-validators:2.9.2"
並且您需要在swagger配置類之上導入BeanValidatorPluginsConfiguration配置文件：
@Configuration @EnableSwagger2 @Import(BeanValidatorPluginsConfiguration.class) public class SpringFoxConfig { ... }
(九)將Swagger Core注釋添加到模型類中
使用JSR-303的優點是，如果您已經使用它們，您可以毫不費力地獲得額外的文檔信息，而無需更改任何代碼。問題是目前，SpringFox不顯示注釋中指定的驗證消息。此外，您可能需要記錄一些更復雜的約束。在這種情況下，您可以使用Swagger Core注釋，它允許您指定其他信息，例如描述。用這些注釋注釋的Person類可以看起來像這樣。
@ApiModel(description = "Class representing a person tracked by the application.") public class Person { @ApiModelProperty(notes = "Unique identifier of the person. No two persons can have the same id.", example = "1", required = true, position = 0) private int id; @ApiModelProperty(notes = "First name of the person.", example = "John", required = true, position = 1) private String firstName; @ApiModelProperty(notes = "Last name of the person.", example = "Doe", required = true, position = 2) private String lastName; @ApiModelProperty(notes = "Age of the person. Non-negative integer", example = "42", position = 3) private int age; // … Constructor, getters, setters, ... }
在類級別，您使用@ApiModel注釋並在字段級別@ApiModelProperty。當然，您可以與JSR-303注釋混合搭配。 @ApiModelProperty的示例對於提供示例值非常有用，這不僅適用於用戶的指導，而且還可以在使用Swagger UI作為REST客戶端來測試服務時預填充請求有效負載。Position屬性很方便指定屬性在文檔中顯示的順序。首先提供重要或必需的屬性或屬於一起的組屬性是有用的。否則，屬性將按字母順序列出。
(十)將Swagger Core注釋添加到控制器類
與使用Swagger核心注釋注釋模型類以提供其他元數據相同，您可以注釋控制器及其方法和方法參數。
- @Api描述了整個控制器
- @ApiOperation用於方法級別的描述
- @ApiParam用於方法參數
@RestController
@RequestMapping("/v2/persons/")
@Api(description = "Set of endpoints for Creating, Retrieving, Updating and Deleting of Persons.")
public class PersonController {
private PersonService personService;
@RequestMapping(method = RequestMethod.GET, produces = "application/json")
@ApiOperation("Returns list of all Persons in the system.")
public List getAllPersons() {
return personService.getAllPersons();
}
@RequestMapping(method = RequestMethod.GET, path = "/{id}", produces = "application/json")
@ApiOperation("Returns a specific person by their identifier. 404 if does not exist.")
public Person getPersonById(@ApiParam("Id of the person to be obtained. Cannot be empty.")
@PathVariable int id) {
return personService.getPersonById(id);
}
@RequestMapping(method = RequestMethod.DELETE, path = "/{id}")
@ApiOperation("Deletes a person from the system. 404 if the person's identifier is not found.")
public void deletePerson(@ApiParam("Id of the person to be deleted. Cannot be empty.")
@PathVariable int id) {
personService.deletePerson(id);
}
@RequestMapping(method = RequestMethod.POST, produces = "application/json")
@ApiOperation("Creates a new person.")
public Person createPerson(@ApiParam("Person information for a new person to be created.")
@RequestBody Person person) {
return personService.createPerson(person);
}
@Autowired
public void setPersonService(PersonService personService) {
this.personService = personService;
}
}
現在您的文檔還應包含所提供的描述：
請注意，我們的控制器和域類現在受到Swagger特定注釋的困擾。可讀性受到很大影響，因為重要的信息在大量的漏洞中丟失了。更糟糕的是 - 當您更改代碼時，以這種方式編寫的文檔不會更新，您需要記住手動更改消息。這會增加您的文檔不同步的風險，因此不值得信任。最好包括一些不明顯的基本信息，而這些信息尚未被自動生成的信息很好地涵蓋。具有參數的描述性名稱以及JSR-303注釋通常可以記錄大部分所需信息。
(十一)從屬性文件加載描述
直接在注釋中提供描述並不是很優雅。它可能占用大量空間，污染您的代碼。你不能真正支持多種語言。如果要修復拼寫錯誤或對文檔進行一些更改，則需要重新構建並重新部署整個應用程序。根據環境，您不能擁有不同的值。不是很靈活。幸運的是，Spring提供了Property占位符的概念。簡而言之，它允許您提供占位符$ {placeholder}而不是硬編碼值。然后在.properties文件中定義占位符的值。Spring從屬性加載數據並注入它而不是占位符。很酷的是，您可以為每種語言提供多個屬性文件。您可以在不同的環境中提供不同的屬性文件。
SpringFox在一些注釋中支持這種機制。這是一種很好的方法，可以將文檔與代碼分離，並具有更大的靈活性。不幸的是，目前只支持一些注釋。因此，例如在模型中，它們在方法級別（@ApiModelProperty）上支持它，但在類級別（@ApiModel）上不支持它。
要完成這項工作，您需要：
- 創建屬性文件，例如swagger.properties
- 輸入您想要的消息作為鍵值對，其中鍵將用作占位符 - 例如person.id =此人的唯一標識符
- 而不是注釋文本插入占位符 - 例如$ {person.id}
- 在類級別注冊配置中的屬性文件 - 例如。 @PropertySource（ “類路徑：swagger.properties”）
結論
SpringFox是一個有用的工具，它可以根據您的Spring控制器和模型類自動生成Swagger文檔。它還可以識別JSR-303注釋，因此您還要記錄模型類的所有約束。它還可以使用核心的swagger類，例如@ApiModelProperty。但要小心，因為這會使你的代碼充滿了大量特定的注釋。只有在SpringFox無法推斷信息本身時才使用它們總是更好。僅在需要添加某些描述時才使用它們，其中類，屬性和方法名稱不能自我解釋。再說一遍，你的API可能是一個紅色標志，說明你的API是神秘的還是太復雜了。如果您保留由SpringFox自動生成的大部分文檔，您可以確保它始終是最新的。除此以外，在代碼中進行更改時，您需要非常小心地更新Core Swagger注釋。如果您的文檔和代碼不匹配，用戶將失去對您的API文檔的信任，並且此類文檔幾乎無用。
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
聲明： 本文轉自 Vojtech Ruzicka的編程博客