swagger——接口文档
一、序言
本文章主要应用于记录自身学习笔记,若有错误,还望大佬指出。
二、基本介绍
swagger是一个规范定义REST ful接口文档的工具,通过使用注解与配置的方式将项目中写好的接口进行规范化展示,避免前后端因为接口不统一而出现数据交互失误。
据说Apifox在接口文档管理方面还要优于swagger,还可进行mock数据,不过因本人对这个工具还没有过具体的了解,也就不多谈及。
本文以介绍swagger为主,不对其他代码做详细补充。
三、常用注解
注解 | 作用 |
---|---|
@Api | 用在请求的类上,例如XXXController,表示对类的说明 |
@ApiMondel | 通常用在实体类上,表示返回的响应数据的信息 |
@ApiModelProperty | 用于属性上,指定响应类的属性 |
@ApiOperation | 用于请求的方法上,说明方法用途、作用 |
@ApiImplicitParams | 用在请求的方法上,表示一组参数说明 |
@ApiImplicitParam | 用在@ApiImplicitParams中,指定一个请求参数的方面,如返回类型,参数介绍等 |
四、使用过程
本文主要以swagger3.0.0为主,其与以往的swagger存在一定差异,本文中会指出目前我所知晓的差异。
1、导入依赖
- 前提条件
<!--web项目,优先导入-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--减少代码量-->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
- swagger3.0.0
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
- swagger3.0.0以下版本
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<!--版本任意-->
<version>XXX</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<!--版本任意-->
<version>XXX</version>
</dependency>
2、进行application.yml文件配置
自springBoot 2.6后使用swagger需要配置路径,不然会报错,启动失败。
server:
# 默认也为8080端口
port: 8080
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher # 匹配路径,不然会报错, Failed to start bean ‘documentationPluginsBootstrapper‘
3、开发实体类和配置类
利用swagger注解对相应内容进行标注,便捷的开发接口文档。
- 实体类User
package swagger.demo.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/**
* User实体类
*/
@Data
@ApiModel(value = "用户实体", description = "[描述] 用户实体")
@AllArgsConstructor
@NoArgsConstructor
public class User {
@ApiModelProperty(value = "用户id,主键")
private Integer id;
@ApiModelProperty(value = "年龄")
private Integer age;
@ApiModelProperty(value = "姓名")
private String name;
}
- 用户控制器UserController
package swagger.demo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import swagger.demo.entity.User;
import java.util.ArrayList;
import java.util.List;
/**
* 用户控制器
*/
@Api(tags = "用户控制器")
@RestController
@RequestMapping("/user")
public class UserController {
@GetMapping("/getAllUsers")
@ApiOperation(value = "获取所有用户", notes = "获取所有用户信息")
public List<User> getAllUserInfo(){
User user = new User(1, 18, "张三");
List<User> userList = new ArrayList<>();
userList.add(user);
return userList;
}
@GetMapping("/page/{pageNum}/{pageSize}")
@ApiOperation(value = "分页查询")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "页码",
required = true, type = "Integer"),
@ApiImplicitParam(name = "pageSize", value = "页条数",
required = true, type = "Integer")
})
public String findByPage(@PathVariable Integer pageNum,
@PathVariable Integer pageSize){
return "ok";
}
}
- 开发配置类SwaggerConfiguration
package swagger.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* 配置类,配置分组,接口详情等
*/
@Configuration
@EnableOpenApi
public class SwaggerConfiguration {
@Bean
public Docket createUserApi(){
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("用户接口组")
.select()
.apis(RequestHandlerSelectors.basePackage("swagger.demo.controller"))
.build();
return docket;
}
/*
* 可以创建其他bean来配置其他分组
* 与createUserApi()类似
* */
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("标题")
.contact(new Contact("name", "url", "email"))
.version("版本号")
.description("描述信息")
.build();
}
}
配置类中也可以不设其他方法
去掉groupName()分组,包路径修改为所有控制类的根路径
即可全部分到默认的default组
swagger3.0.0的配置类中所需注解为@EnableOpenApi
其他较低版本为@EnableSwagger2
4、访问页面
- swagger3.0.0: http://localhost:端口号/swagger-ui/index.html
- 其他较低版本:http://localhost:端口号/swagger-ui.html
- 效果如下:
五、存在的问题
swagger运行时会报错java.lang.NumberFormatException: For input string: ““,存在格式异常,据悉是因为在swagger内部未对空串做排查,作为一个摆烂之王,我也就懒得去探查解决的方法了,希望各位大佬能提出解决方案以及本文存在的其他问题,万分感谢。
这篇好文章是转载于:学新通技术网
- 版权申明: 本站部分内容来自互联网,仅供学习及演示用,请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系,请提供相关证据及您的身份证明,我们将在收到邮件后48小时内删除。
- 本站站名: 学新通技术网
- 本文地址: /boutique/detail/tanhgbhfef
系列文章
更多
同类精品
更多
-
photoshop保存的图片太大微信发不了怎么办
PHP中文网 06-15 -
Android 11 保存文件到外部存储,并分享文件
Luke 10-12 -
word里面弄一个表格后上面的标题会跑到下面怎么办
PHP中文网 06-20 -
《学习通》视频自动暂停处理方法
HelloWorld317 07-05 -
photoshop扩展功能面板显示灰色怎么办
PHP中文网 06-14 -
微信公众号没有声音提示怎么办
PHP中文网 03-31 -
excel下划线不显示怎么办
PHP中文网 06-23 -
怎样阻止微信小程序自动打开
PHP中文网 06-13 -
excel打印预览压线压字怎么办
PHP中文网 06-22 -
TikTok加速器哪个好免费的TK加速器推荐
TK小达人 10-01