将Swagger与Spring Boot REST API集成

在上一篇文章中，我谈到了我使用Spring Boot创建RESTFul Services的经验。在创建REST API时，正确的文档是其中的必需部分。

昂首阔步是什么？

Swagger （Swagger 2）是用于描述和记录REST API的规范。它指定了REST Web服务的格式，包括URL，资源，方法等。Swagger将根据应用程序代码生成文档，并处理渲染部分。

在本文中，我将把Swagger 2文档集成到基于Spring Boot的REST Web服务中。因此，我将使用Springfox实现来生成swagger文档。如果您想知道如何运行/构建Spring Boot项目，请参考我以前的文章。

Springfox提供了两个依赖关系来生成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支持。为了记录服务，Springfox使用了Docket。 Docket帮助配置了要记录的服务子集，并按名称将其分组，等等。最隐蔽的概念是，Springfox通过使用基于Spring配置的API语义在运行时检查应用程序来工作。换句话说，您必须创建一个使用spring的@Configuration的Spring Java Configuration类。

在我的示例中，我根据添加的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();}
}

由于我添加了两个控制器，因此这将分别对每个控制器相关的API进行分组（标记）。

开箱即用，Springfox提供了五个谓词，它们是任何类，没有类，具有ClassAnnotation，withMethodAnnotation和basePackage。

养蜂信息

Swagger提供了一些默认值，例如“ API文档”，“通过联系电子邮件创建”，“ Apache 2.0”。因此，您可以通过添加apiInfo（ApiInfo apiInfo）方法来更改这些默认值。 ApiInfo类包含有关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后，生成的文档将类似于以下内容：

控制器和POJO级别文档

@Api注释用于解释每个rest控制器类。

@ApiOperation批注用于解释以描述资源和方法。

@ApiResponse批注用于解释描述可以由操作返回的其他响应。例如：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源代码。