Springboot+Swagger3自动生成API文档(附项目地址)
Springboot-cli 开发脚手架系列
Springboot系列:Springboot+Swagger3自动生成API文档
文章目录
- Springboot-cli 开发脚手架系列
- 简介
-
- 前言
- 1. 环境
- 2. 编写配置文件
- 3. 编写接口
- 4. 效果展示
- 5. 源码分享
简介
- 号称世界上最流行的API框架
- RestFul API文档在线生成工具—API文档与API同步更新
- 可以直接运行,可以在线测试API接口
- 支持多种语言:(Java,PHP…)
前言
致力于让开发者快速搭建基础环境并让应用跑起来,提供使用示例供使用者参考,让初学者快速上手。
- 项目源码github地址
- 项目源码国内gitee地址
1. 环境
- 引入依赖
pom.xml
- 注意
spring-boot-starter-parent 不能大于2.5.3 否则swagger3报错
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
2. 编写配置文件
SwaggerConfig.java
@EnableOpenApi@Configurationpublic class SwaggerConfig { @Bean public Docket createRestApi() { //swagger设置,基本信息,要解析的接口及路径等 return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() //设置通过什么方式定位需要自动生成文档的接口,这里定位方法上的@ApiOperation注解 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //接口URI路径设置,any是全路径,也可以通过PathSelectors.regex()正则匹配 .paths(PathSelectors.any()) .build(); } /** * 生成接口信息,包括标题、联系人,联系方式等 */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger3接口文档") .description("如有疑问,请联系开发工程师") .contact(new Contact("xx", "www.xx.com", "xx@qq.com")) .version("1.0") .build(); }}
3. 编写接口
- 创建实体
User .java
@Data@Accessors(chain = true)@ApiModel("用户信息表")public class User { @ApiModelProperty("用户id") private Long userId; @ApiModelProperty("用户名") private String username; @ApiModelProperty("用户性别") private String sex;}
- 创建web接口
UserController.java
@RestController@Api(tags = "UserController:用户信息管理接口")public class UserController { @GetMapping("/get") @ApiOperation("获取数据") public User get() { return new User().setUserId(1L).setSex("男").setUsername("王小锤"); } @PostMapping("/add") @ApiOperation("添加数据") public String add(User user) { return "添加数据成功"; } @DeleteMapping("/del") @ApiOperation("删除数据") public String del() { return "删除数据成功"; } @PostMapping("/upd") @ApiOperation("更新数据") public String upd() { return "更新数据成功"; }}
4. 效果展示
-
启动项目
-
浏览器输入
http://{ip}:{port}/swagger-ui/index.html#/
-
接口信息
-
模拟http进行请求
-
实体文档
5. 源码分享
本项目已收录
- Springboot-cli开发脚手架,集合各种常用框架使用案例,完善的文档,致力于让开发者快速搭建基础环境并让应用跑起来。
- 项目源码github地址
- 项目源码国内gitee地址