在上一篇文章中，我談到了我使用Spring Boot創(chuàng)建RESTFul Services的經(jīng)驗。 在創(chuàng)建REST API時，正確的文檔是其中的必需部分。

昂首闊步是什么？

Swagger （Swagger 2）是用于描述和記錄REST API的規(guī)范。 它指定了REST Web服務(wù)的格式，包括URL，資源，方法等。Swagger將根據(jù)應(yīng)用程序代碼生成文檔，并處理渲染部分。

在本文中，我將把Swagger 2文檔集成到基于Spring Boot的REST Web服務(wù)中。 因此，我將使用Springfox實現(xiàn)來生成swagger文檔。 如果您想知道如何運(yùn)行/構(gòu)建Spring Boot項目，請參考我以前的文章。

Springfox提供了兩個依賴關(guān)系來生成API Doc和Swagger UI。 如果您不希望將Swagger UI集成到您的API級別，則無需添加Swagger UI依賴項。

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.7.0</version></dependency>

@ EnableSwagger2注釋在類中啟用Springfox Swagger支持。 為了記錄服務(wù)，Springfox使用了Docket。 Docket幫助配置了要記錄的服務(wù)子集，并按名稱將其分組，等等。最隱蔽的概念是，Springfox通過使用基于Spring配置的API語義在運(yùn)行時檢查應(yīng)用程序來工作。 換句話說，您必須創(chuàng)建一個使用spring的@Configuration的Spring Java Configuration類。

在我的示例中，我根據(jù)添加的RestController類生成了龐大的文檔。

import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration @EnableSwagger2 public class ApplicationConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers")).paths(PathSelectors.any()).build();} }

由于我添加了兩個控制器，因此這將分別對每個控制器相關(guān)的API進(jìn)行分組（標(biāo)記）。

開箱即用，Springfox提供了五個謂詞，它們是任何類，沒有類，具有ClassAnnotation，withMethodAnnotation和basePackage。

養(yǎng)蜂信息

Swagger提供了一些默認(rèn)值，例如“ API文檔”，“通過聯(lián)系電子郵件創(chuàng)建”，“ Apache 2.0”。 因此，您可以通過添加apiInfo（ApiInfo apiInfo）方法來更改這些默認(rèn)值。 ApiInfo類包含有關(guān)API的自定義信息。

@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers")).paths(PathSelectors.any()).build();}private ApiInfo getApiInfo() {Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");return new ApiInfoBuilder().title("Example Api Title").description("Example Api Definition").version("1.0.0").license("Apache 2.0").licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").contact(contact).build();}

添加ApiInfo后，生成的文檔將類似于以下內(nèi)容：

控制器和POJO級別文檔

@Api注釋用于解釋每個rest控制器類。

@ApiOperation批注用于解釋以描述資源和方法。

@ApiResponse批注用于解釋描述可以由操作返回的其他響應(yīng)。例如：200 ok或202接受，等等。

@ApiModelProperty批注描述POJO（Bean）類的屬性。

添加上述注釋后，最終生成的swagger文檔如下所示：

Spring RestController類：

package com.chandana.helloworld.controllers;import com.chandana.helloworld.bean.Greeting; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController;@RestController @RequestMapping("/api") @Api(value = "user", description = "Rest API for user operations", tags = "User API") public class HelloWorldController {@RequestMapping(value = "/hello/{name}", method = RequestMethod.GET, produces = "application/json")@ApiOperation(value = "Display greeting message to non-admin user", response = Greeting.class)@ApiResponses(value = {@ApiResponse(code = 200, message = "OK"),@ApiResponse(code = 404, message = "The resource not found")})public Greeting message(@PathVariable String name) {Greeting msg = new Greeting(name, "Hello " + name);return msg;} }

問候模型類：

package com.chandana.helloworld.bean;import io.swagger.annotations.ApiModelProperty;public class Greeting {@ApiModelProperty(notes = "Provided user name", required =true)private String player;@ApiModelProperty(notes = "The system generated greeting message" , readOnly =true)private String message;public Greeting(String player, String message) {this.player = player;this.message = message;}public String getPlayer() {return player;}public void setPlayer(String player) {this.player = player;}public String getMessage() {return message;}public void setMessage(String message) {this.message = message;} }

AppConfig類：

package com.chandana.helloworld.config;import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration @EnableSwagger2 public class ApplicationConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers")).paths(PathSelectors.any()).build();}private ApiInfo getApiInfo() {Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");return new ApiInfoBuilder().title("Example Api Title").description("Example Api Definition").version("1.0.0").license("Apache 2.0").licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").contact(contact).build();} }

您也可以從我的GitHub存儲庫下載Swagger Spring Boot Project源代碼 。

翻譯自: https://www.javacodegeeks.com/2017/09/integrating-swagger-spring-boot-rest-api.html

總結(jié)

以上是生活随笔為你收集整理的将Swagger与Spring Boot REST API集成的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

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