SpringBoot使用Swagger2构建API文档
Posted yong-8379
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了SpringBoot使用Swagger2构建API文档相关的知识,希望对你有一定的参考价值。
第一步:在pom.xml中加入Swagger2依赖
<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>
第二步:创建Swagger2配置类
package com.offcn.springbootdemo.config; 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.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2//开启在线文档 public class SwaggerConfig {
//配置核心配置信息 public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("需要生成API文档的文件的路径,例如:com.my.controller.CarController")) .paths(PathSelectors.any()) .build(); }
//声明api/文档属性 构建器 private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("文档标题") .description("文档描述") .termsOfServiceUrl("url地址例如:http://abc.com/") .contact("联系方式") .version("版本号") .build(); } }
第三步:对指定文件添加文档注释
通过@ApiOperation注释来给API增加说明
使用在Api类的接口方法上,主要属性有value(接口名称)、notes(注释)、hidden(是否隐藏)、httpMethod、ignoreJsonView、response、responseHeaders等等,某些属性注解可自动识别,无需配置。
通过@ApiImplicitParams、@ApiImplicitParam注释来给参数增加说明
使用在Api类的接口方法上,对接口参数进行说明,@ApiImplicitParams只有一个属性value,@ApiImplicitParam主要属性有name(参数名称)、value(参数说明)、required(是否必需)、dataType(数据类型)、paramType(参数类型)、dataTypeClass、defaultValue、readOnly等。
package com.offcn.springbootdemo.controller; import com.offcn.springbootdemo.bean.User; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import java.util.ArrayList; import java.util.Collections; import java.util.List; @RestController @RequestMapping("/users-test") public class UserController { private List<User> listUser= Collections.synchronizedList(new ArrayList<User>()); /** * 更新指定id用户信息 * @param id * @param user * @return */ @PutMapping("/{id}") @ApiOperation(value = "更新指定id用户信息",notes = "根据id更新用户信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "Long"), @ApiImplicitParam(name = "user",value = "用户实体user",required = true,dataType = "User") }) public String updateUser(@PathVariable("id") Long id,User user) { for (User user2 : listUser) { if(user2.getId()==id) { user2.setName(user.getName()); user2.setAge(user.getAge()); } } return "success"; } /*** * 删除指定id用户 * @param id * @return */ @DeleteMapping("/{id}") @ApiOperation(value = "删除指定id的用户信息",notes = "根据id删除用户信息") @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "Long") public String deleteUser(@PathVariable("id") Long id) { listUser.remove(getUser(id)); return "success"; } }
第四步:查看生成的API在线文档
重启应用,然后访问地址:http://localhost:8080/swagger-ui.html
以上是关于SpringBoot使用Swagger2构建API文档的主要内容,如果未能解决你的问题,请参考以下文章
springboot集成swagger2构建RESTful API文档
Spring Boot中使用Swagger2构建强大的RESTful API文档
企业级 SpringBoot 教程 springboot集成swagger2,构建优雅的Restful API