- 使用步骤
-
一.下载依赖 去maven官网收索springfox-swag
图片.png
介绍
在以往的web项目开发中，大家会经常的使用postman来测试接口和使用文档来编写接口，大量的重复劳动，相信大家已经厌烦，为了解决它使大家能有更多的时间专注于编码，一款叫做swagger2的软件诞生了，只需要导入依赖，并在控制层加上@Api这个注解就能快速生成一个接口文档，并能像postman一样对接口进行测试。
快速入门
导入依赖后直接加上@EnableSwagger2 就可以了
第一步、在pom中导入依赖
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency></pre>
第二步、在Application中加入注解@EnableSwagger2
第三步、打开URL
打开URL，URL格式为：你的端口+/swagger-ui.html
例如：http://localhost:9011/swagger-ui.html
[图片上传失败...(image-a2cf79-1617613050501)]
测试接口
1、点开其中一个接口
[图片上传失败...(image-40653d-1617613050501)]
2、输入ID点击Try it out
[图片上传失败...(image-5baa0d-1617613050501)]
3、查看测试结果
[图片上传失败...(image-5896fc-1617613050501)]
定制化你的接口文档
如果觉得页面内容太少了，对它默认的内容不太满意，需要加点描述使它更加详细，也可以选择自己加上一些描述内容。
编写一个配置类
package com.tang.swagger.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.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;
//标注此类是配置类 里面有@Component吧自身注入到spring进行管理
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 扫描所有带@ApiOperation注解的类
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2).groupName("A")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.tang.swagger.controller")) //包名
.build();
}
@Bean
public Docket api1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("B")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.tang.swagger.controller"))
.build();
}
//api接口作者相关信息
private ApiInfo apiInfo() {
Contact contact = new Contact("文档作者信息", "", "XXX@qq.com");
ApiInfo apiInfo = new ApiInfoBuilder().license("").title("唐的SwaggerApi").description("接口文档").contact(contact).version("3.0").build();
return apiInfo;
}
}
@Configuration
public class SwaggerConfig {
// 扫描所有带@ApiOperation注解的类
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
//api接口作者相关信息
private ApiInfo apiInfo() {
Contact contact = new Contact("文档作者信息", "", "XXX@qq.com");
ApiInfo apiInfo = new ApiInfoBuilder().license("").title("标题").description("接口文档").contact(contact).version("3.0").build();
return apiInfo;
}
}</pre>
[图片上传失败...(image-7cd9f8-1617613050501)]
在Controller类和方法上加注解
在类上加@Api(description = "这是我全部的get方法")
在方法上加@ApiOperation(value = "根据ID查询一个品牌")
注解
--value 对资源的标签名
--description 描述
@ApiOperation ：对方法的注解
--value 对资源的标签名
--notes 对方法操作的描述
@ApiImplicitParams ：对多个参数的描述的集合
@ApiImplicitParam：在@ApiImplicitParams里面
--name 属性字段名
--value 属性字段含义
--required 是否必填（true/false）
--paramType 参数位置（"query"为参数放置url,"body"为post方法放在body里...）
paramType：表示参数放在哪个地方
header-->请求参数的获取：@RequestHeader(代码中接收注解)
query-->请求参数的获取：@RequestParam(代码中接收注解)
path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
body-->请求参数的获取：@RequestBody(代码中接收注解)
form（不常用）
--dataType 参数类型（"String"、"int"...）
@ApiModel ：对实体类的描述
@ApiModelProperty ：对实体字段的描述
--name 属性名称
--value 属性描述
--hidden 是否不再swagger页面展示（true/false）</pre>
