1.为什么要使用Swagger?
前后端协作开发过程中,时间周期一长,接口文档就变得难以维护,而我们通过swagger 只需要平常在写代码的时候加上一些注解,就可以生成一个接口在线文档,进行一些简单的功能测试!
2.如何使用Swagger?
1).需要在pom.xml中引用jar包
复制出来:
<!-- swagger start -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<!-- swagger end -->
2).配置swagger文档的配置类
package com.test;
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;
/**
* 功能描述: swagger文档的配置类
* @Author: tanghh18
* @Date: 2019/9/27 13:51
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage
("com.test.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("前端 API")
//创建人
.contact(new Contact("soup_tang", "http://localhost:8084/", "[email protected]"))
//版本号
.version("1.0")
//描述
.description("加油!")
.build();
}
}
3. Swagger常用的注解
@Api() 主要是用来描述当前类的作用,description是在swagger文档页面展示的备注信息
@ApiOperation() value这个参数不在文档上面展示,notes是在文档上面展示的内容,httpMethod 是get 还是post请求
@ApiModelProperty 主要是用来描述当前这个参数的作用
还有一些其他的注解:
(1)@ApiImplicitParams : 用在方法上包含多个参数说明。
(2)@ApiImplicitParam:用在方法上包含一个参数说明。
paramType:指定参数放在哪个地方。
name:参数名
dataType:参数类型
required:参数是否必须传
value:说明参数
defaultValue:参数的默认值
header:请求参数放置于Request Header,使用@RequestHeader 获取。
query:请求参数放置于请求地址,使用@RequestParam获取
path:用于restful接口。
(3)@ApiResponses:用于表示一组响应。
(4)@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息。
code:数字,例如400。
message:信息,例如"请求参数没填好"。
response:抛出异常的类 。
————————————————
版权声明:本文为CSDN博主「XuDanT」的原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接及本声明。
原文链接:https://blog.csdn.net/xudant/article/details/82856555
4.如何在项目访问当前生成这个swagger文档?
我此时项目的端口是8084 所以在页面上访问路径为:http://localhost:8084/swagger-ui.html