> 文档中心 > Springboot+Swagger3自动生成API文档(附项目地址)

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#/
    Springboot+Swagger3自动生成API文档(附项目地址)

  • 接口信息
    Springboot+Swagger3自动生成API文档(附项目地址)

  • 模拟http进行请求
    Springboot+Swagger3自动生成API文档(附项目地址)

  • 实体文档
    Springboot+Swagger3自动生成API文档(附项目地址)

5. 源码分享

本项目已收录

  • Springboot-cli开发脚手架,集合各种常用框架使用案例,完善的文档,致力于让开发者快速搭建基础环境并让应用跑起来。
  • 项目源码github地址
  • 项目源码国内gitee地址