1.swagger介绍
Swagger是一个规范和完整的框架,用于生成,描述,调用和可视化 RESTful风格的WEB服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
Swagger的作用:
1,接口的文档在线自动生成。
2,功能测试。
2.接入步骤
2.1 在maven中添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.4</version>
</dependency>
2.2 创建swagger的配置类
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author zj
* @date 2019-11-28
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())//添加说明
.select()
.apis(RequestHandlerSelectors.basePackage("com.XX.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
.title("XXXX接口文档")
.description("XXXX接口文档")
.version("1.0")
.build();
}
}
2.3 swagger常用注解使用说明
1.@Api:用在类上,说明该类的作用。
2. @ApiOperation:注解来给API增加方法说明。
3.@ApiImplicitParams:用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
5.@ApiResponses: 用于表示一组响应。
@ApiResponse: 用在@ApiResponses中,一般用于表达一个错误的响应信息。
code:数字,例如400
-
- message:信息,例如"请求参数没填好"
- response:抛出异常的类
7.@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
2.4 接口文档页面的访问方式
1.springfox-swagger-ui
项目ip:端口/swagger-ui.html 示例:localhost:8080/swagger-ui.html
2.swagger-bootstrap-ui
项目ip:端口/doc.html 示例:localhost:8080/doc.html