SpringBoot+Swagger2实现自动生成API文档

Swagger概述

Swagger是一组围绕OpenAPI规范构建的开源工具，可帮助设计、构建、记录和使用REST API。
简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口
修改了后，swagger可以实现自动的更新，而不需要认为的维护这个接口进行测试。

Swagger2 配置

需要在你的SpringBoot工程中加入如下pom

             <!-- swagger2 配置 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.4.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.4.0</version></dependency>

在配置好pom文件之后，我们需要开启Swagger2,我们可以使用两种方式来实现。第一种直接在启动类上加入@EnableSwagger2注解，即可
第二种则是新建配置类来自定义一些Swagger2的属性，如下

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 Swagger2 {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.imooc.controller")).paths(PathSelectors.any()).build();}/** @Description: 构建 api文档的信息*/private ApiInfo apiInfo() {return new ApiInfoBuilder()// //大标题.title("测试系统 RESTful API")// 版本号.version("2.0")
//                .termsOfServiceUrl("NO terms of service")// 描述.description("API 描述")//作者.contact(new Contact("zhao", "https://blog.csdn.net/u011342403", "1182867739@qq.com"))
//                .license("The Apache License, Version 2.0")
//                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html").build();}
}

在我们的Controller和Model中加入一些Swagger2的注解配置

@RestController
@Api(value="用户注册登录接口",tags="登录注册controller")
public class RegistLoginController {@AutowiredUserService userService;@PostMapping(value="/regist")@ApiOperation(value="用户注册",notes="注册接口")public IMoocJSONResult regist(@RequestBody Users users){if (StringUtils.isBlank(users.getUsername())||StringUtils.isBlank(users.getPassword())) {return IMoocJSONResult.errorMsg("用户名或密码不能为空");}if (userService.queryUsernameIsExist(users.getUsername())) {return IMoocJSONResult.errorMsg("该用户名已存在，请重新注册");}else {userService.saveUser(users);}return IMoocJSONResult.ok();}
}

Model配置

@ApiModel(value="用户对象",description="这是用户对象")
public class Users {@Id@ApiModelProperty(hidden=true)private String id;/*** 用户名*/@ApiModelProperty(value="用户名",name="username",example="imooc",required=true)private String username;/*** 密码*/@ApiModelProperty(value="密码",name="password",example="123456",required=true)private String password;/*** 我的头像，如果没有默认给一张*/@Column(name = "face_image")@ApiModelProperty(hidden=true)private String faceImage;/*** 昵称*/private String nickname;/*** 我的粉丝数量*/@Column(name = "fans_counts")@ApiModelProperty(hidden=true)private Integer fansCounts;/*** 我关注的人总数*/@Column(name = "follow_counts")@ApiModelProperty(hidden=true)private Integer followCounts;/*** 我接受到的赞美/收藏 的数量*/@Column(name = "receive_like_counts")@ApiModelProperty(hidden=true)private Integer receiveLikeCounts;

使用上述注解可义定义在传入参数时，是否必须传入等属性。

Swagger常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数
需要注意的时上述的参数注解在后续的版本中已经修改了，这个要引起注意

Swagger错误java.lang.NoClassDefFoundError: io/swagger/models/Contact

这个错误我基本断定与Swagger版本和SpringBoot携带的Spring版本有关，上述Swagger2.4.0的无法与SpringBoot2版本配合使用，因此在我们后续的使用中需要注意版本的配合关系

SpringBoot+Swagger2实现自动生成API文档相关推荐

springboot 集成 swagger 自动生成API文档
Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案. S ...
SpringBoot 自动生成API文档
SpringBoot 自动生成API文档在做项目的时候,如果项目是前后分离的,后端一定要和前端或者是移动端对接接口,那么问题来了,接口是不是要自己写给他们看,一般的会采用Excel或者Word来写, ...
超详细！使用swagger自动生成Api文档（swagger-ui）
介绍 swagger是什么? swagger-ui 使用swagger-ui 简单使用 swagger api注解本文参考: 介绍这里是一些介绍,如果想直接看如何使用,请直接跳过这部分.但如果有时 ...
【接口文档】Django restful framework中自动生成API文档
Django restful framework中自动生成API文档一.Swagger概述 1.引言当接口开发完成,紧接着需要编写接口文档.传统的接口文档使用Word编写,or一些接口文档管理平台 ...
swagger php修改成中文,PHP使用swagger自动生成API文档
使用 swagger 自动生成 API 文档使用 swagger 自动生成 API 文档,有需要的朋友可以参考下. 一.下载 swagger-ui 直接上传服务器二.下载 swagger-php ...
windows api中文文档_Web服务开发：Spring集成Swagger，3步自动生成API文档
目录: 1,Spring Boot集成Swagger 2,Swagger接口文档页面 3,常见问题和解决方法在Sping开发REST接口服务时,API文档是不可缺少的一个重要部分.Swagger框架 ...
swagger 修改dto注解_Web服务开发：Spring集成Swagger，3步自动生成API文档
目录: 1,Spring Boot集成Swagger 2,Swagger接口文档页面 3,常见问题和解决方法在Sping开发REST接口服务时,API文档是不可缺少的一个重要部分.Swagger框架 ...
PHP使用swagger-php自动生成api文档（详细附上完整例子）
thinkphp5结合swagger自动生成接口文档整体介绍 swagger-php.swagger-ui.swagger-editor swagger-ui:主要就是放到tp项目public目录下 ...
如何利用showdoc自动生成API文档
介绍 showdoc是一个适合IT团队的文档工具,阅读本文前需要对showdoc有基本了解 .基本介绍可看:https://www.showdoc.cc/help 对于写API文档这件事,虽然说文本编 ...