怎么在SpringBoot中利用Swagger2生成一个接口文档

tangjin

作者

本篇文章为大家展示了怎么在SpringBoot中利用Swagger2生成一个接口文档，内容简明扼要并且容易理解，绝对能使你眼前一亮，通过这篇文章的详细介绍希望你能有所收获。

准备工作

一个SpringBoot项目，可以直接去官网生成一个demo 。

一个用户类。

packagecn.itweknow.springbootswagger.model;

importjava.io.Serializable;


publicclassUserimplementsSerializable{

privateIntegerid;

privateStringname;

privateStringpassword;

privateStringemail;
}

项目依赖

Web Service肯定是一个Web项目，所以我们这里依赖了 spring-boot-starter-web 包，其他两个包就是和 Swagger 相关的包了。

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>

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

Swagger配置

Springfox Docket实例为Swagger配置提供了便捷的配置方法以及合理的默认配置。我们将通过创建一个Docket实例来对Swagger进行配置，具体配置如下所示。

@Configuration
@EnableSwagger2
publicclassSwaggerConfigextendsWebMvcConfigurationSupport{

@Bean
publicDocketproductApi(){
returnnewDocket(DocumentationType.SWAGGER_2).select()
//扫描的包路径
.apis(RequestHandlerSelectors.basePackage("cn.itweknow.springbootswagger.controller"))
//定义要生成文档的Api的url路径规则
.paths(PathSelectors.any())
.build()
//设置swagger-ui.html页面上的一些元素信息。
.apiInfo(metaData());
}

privateApiInfometaData(){
returnnewApiInfoBuilder()
//标题
.title("SpringBoot集成Swagger2")
//描述
.description("这是一篇博客演示")
//文档版本
.version("1.0.0")
.license("ApacheLicenseVersion2.0")
.licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
.build();
}

@Override
protectedvoidaddResourceHandlers(ResourceHandlerRegistryregistry){
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

上述代码中的addResourceHandlers方法添加了两个资源处理程序，这段代码的主要作用是对Swagger UI的支持。

API文档

好了，到这一步，我们已经在一个SpringBoot项目中配置好了Swagger。现在，我们就来看一下如何去使用他。首先我们定义了一个 Controller 并提供了两个接口：

通过用户id获取用户
用户登录

@RestController
@RequestMapping("/user")
@Api(description="用户相关接口")
publicclassUserController{

/**
*通过id查询用户
*@return
*/
@RequestMapping(value="/get",method=RequestMethod.GET)
@ApiOperation("根据id获取用户")
publicUsergetUserById(@ApiParam(value="用户id")Integerid){
returnnewUser();
}

@RequestMapping(value="/login",method=RequestMethod.POST)
@ApiOperation("用户登录")
publicUserlogin(@RequestBodyUseruser){
returnnewUser();
}
}

相信大家都注意到了，这个 Controller 里面多了很多新的注解，比如说 @Api , @ApiOperation 等，下面我们就来一一解释一下。

@Api,这个注解是用在Controller类上面的，可以对Controller做必要的说明。
@ApiOperation，作用在具体的方法上，其实就是对一个具体的API的描述。
@ApiParam，对API参数的描述。

到这里，其实我们的Swagger就已经可以有效果了，让我们将项目运行起来先看看效果。访问 http://localhost:8080/swagger-ui.html 即可。

Model

在上面的图中可以看到在页面的下方有一个Models的标签，那么这个是啥呢。其实这个就是我们API中出现的一些对象的文档，我们也可以通过注解来对这些对象中的字段做一些说明，以方便使用者理解。以文章开头提到的 User 类来做一个说明。

@ApiModel("用户实体")
publicclassUserimplementsSerializable{

@ApiModelProperty(value="用户id")
privateIntegerid;

@ApiModelProperty(value="用户名称",required=true)
privateStringname;

@ApiModelProperty(value="密码",required=true)
privateStringpassword;

@ApiModelProperty(value="用户邮箱")
privateStringemail;
}

我们来看一下 User 类在Swagger上是如何展示的：