使用Swagger自动生成API文档~拿来即用
一、什么是Swagger
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
二、作用
-
接口文档在线自动生成
-
功能测试
三、Swagger使用的注解及其说明
-
@Api:用在类上面,说明当前类的作用
-
@ApiOperation:注解来给API增加方法说明。
-
@ApiImplicitParams:用来注解来给方法入参增加说明。
-
@ApiResponses:用于表示一组响应
-
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
-
code:数字,例如400
-
message:信息,例如"请求参数没填好"
-
response:抛出异常的类
-
@ApiModel
-
@ApiModelProperty:描述一个model的属性
-
@ApiImplicitParam的参数说明
-
paramType:指定参数放在哪个地方
-
header:请求参数放置于Request Header,使用@RequestHeader获取
-
query:请求参数放置于请求地址,使用@RequestParam获取
-
path:(用于restful接口)-->请求参数的获取:@PathVariable
-
name:参数名
-
dataType:参数类型
-
required:参数是否必须传
-
value:说明参数的意思
-
defaultValue:参数的默认值
四、使用过程
-
引入依赖
-
<dependencies>
-
<dependency>
-
<groupId>io.springfox</groupId>
-
<artifactId>springfox-boot-starter</artifactId>
-
<version>3.0.0</version>
-
</dependency>
-
<dependency>
-
<groupId>org.projectlombok</groupId>
-
<artifactId>lombok</artifactId>
-
<version>1.18.24</version>
-
</dependency>
-
</dependencies>
2.创建Swagger配置类
-
import org.springframework.context.annotation.Bean;
-
import org.springframework.context.annotation.Configuration;
-
import org.springframework.util.StringUtils;
-
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;
-
-
import java.util.ArrayList;
-
-
/**
-
* Swagger配置类
-
* 在与spring boot集成时,放在与Application.java同级的目录下。
-
* 通过@Configuration注解,让Spring来加载该类配置。
-
* 再通过@EnableSwagger2注解来启用Swagger。
-
*/
-
-
-
-
public class Swagger {
-
/**
-
* 创建API应用
-
* apiInfo() 增加API相关信息
-
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
-
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
-
*
-
* @return
-
*/
-
-
public Docket createRestApi() {
-
return new Docket(DocumentationType.SWAGGER_2)
-
.apiInfo(apiInfo())
-
.select()
-
.apis(RequestHandlerSelectors.basePackage("com.example.swgger"))
-
.paths(PathSelectors.any())
-
.build();
-
}
-
-
/**
-
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
-
* 访问地址:http://项目实际地址/swagger-ui.html
-
* @return
-
*/
-
private ApiInfo apiInfo() {
-
return new ApiInfoBuilder()
-
.title("TY-Java-JY-2202(Spring Boot中使用Swagger构建RESTful APIs)")
-
.description("主要描述")
-
.termsOfServiceUrl("http://www.qfedu.com")
-
.contact(new Contact("Where are you come from","属于自己的网址哟","我自己的个人邮箱哈~~~"))
-
.version("1.0")
-
.build();
-
}
-
}
❗ 在项目启动之后,可以通过这个路径来访问API文档。http://项目实际地址/swagger-ui.html
例如:http://localhost:8080/swagger-ui/index.html 【如果你在Springboot的配置文件中没有修改端口号,可以直接通过这个链接来访问】
-
可能会出现的错误以及原因分析
SpringBoot更新至2.6.0,引发了这个bug。
在配置文件中添加这一栏就行
-
#application.propertise中这么写
-
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
-
接口示例
注解参考第三点-------->>>>>>>>
-
import io.swagger.annotations.Api;
-
import io.swagger.annotations.ApiImplicitParam;
-
import io.swagger.annotations.ApiImplicitParams;
-
import io.swagger.annotations.ApiOperation;
-
import lombok.extern.slf4j.Slf4j;
-
import org.springframework.util.StringUtils;
-
import org.springframework.web.bind.annotation.*;
-
-
-
-
-
public class HelloController {
-
-
-
-
-
-
-
-
-
-
public String updatePassword( Integer userId, String password,
-
String newPassword){
-
if(userId <= 0 || userId > 2){
-
return "未知的用户";
-
}
-
if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
-
return "密码不能为空";
-
}
-
if(password.equals(newPassword)){
-
return "新旧密码不能相同";
-
}
-
return "密码修改成功!";
-
}
-
-
-
}
今天的分享就到这里啦~~~~
下一期预告 knife4j的分享!!!!
这篇好文章是转载于:学新通技术网
- 版权申明: 本站部分内容来自互联网,仅供学习及演示用,请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系,请提供相关证据及您的身份证明,我们将在收到邮件后48小时内删除。
- 本站站名: 学新通技术网
- 本文地址: /boutique/detail/tanhhaeeke
-
photoshop保存的图片太大微信发不了怎么办
PHP中文网 06-15 -
《学习通》视频自动暂停处理方法
HelloWorld317 07-05 -
word里面弄一个表格后上面的标题会跑到下面怎么办
PHP中文网 06-20 -
Android 11 保存文件到外部存储,并分享文件
Luke 10-12 -
photoshop扩展功能面板显示灰色怎么办
PHP中文网 06-14 -
微信公众号没有声音提示怎么办
PHP中文网 03-31 -
excel下划线不显示怎么办
PHP中文网 06-23 -
excel打印预览压线压字怎么办
PHP中文网 06-22 -
TikTok加速器哪个好免费的TK加速器推荐
TK小达人 10-01 -
怎样阻止微信小程序自动打开
PHP中文网 06-13