0
点赞
收藏
分享

微信扫一扫

Swagger 简单快速入门教程

一、使用 springfox生成接口UI

1、导入springfox-boot-starter依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>

2、配置config

@Configuration
@EnableOpenApi
@Slf4j
public class SwaggerConfig extends WebMvcConfigurationSupport {

/**
* 设置静态资源映射
*/

@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
log.info("开始进行静态资源映射....");
registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
}

@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30) // 选择文档类型 OpenApi 3.0
.apiInfo(apiInfo()) //配置swagger信息
.enable(true) // 是否开启 默认开启;
.groupName("reggie") // reggie
.select() // 选择
.apis(RequestHandlerSelectors.basePackage("com.xy.reggie.controller")) // 扫描的包路径下的类
.build(); // 创建
}

private ApiInfo apiInfo() {
return new ApiInfo(
"reggie 文档",
"reggie 文档",
"v1.0",
"https://www.xxx.edu.cn/",
new Contact("谢阳", "https://blog.51cto.com/learningfish", "xxxx@qq.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}

3、swagger的Api介绍

姓名 描述
@Api 将类标记为 Swagger 资源(一般用于描述Controller)
@ApiImplicitParam 表示 API 操作中的单个参数 (一般用于描述具体方法参数)
@ApiImplicitParams 允许多个 ApiImplicitParam 对象列表的包装器(一般用于包裹@ApiImplicitParam)
@ApiModel 提供有关 Swagger 模型的其他信息 (一般用于描述Controller方法参数的pojo类)
@ApiModelProperty 添加和操作模型属性的数据(一般用于描述pojo的属性)
@ApiOperation 描述针对特定路径的操作或通常是 HTTP 方法。(一般用于描述Controller方法)
@ApiParam 为操作参数添加额外的元数据。
@ApiResponse 描述操作的可能响应。
@ApiResponses 允许多个 ApiResponse 对象列表的包装器。
@Authorization 声明要在资源或操作上使用的授权方案。
@AuthorizationScope 描述 OAuth2 授权范围。
  • @Api用法如下:
@Slf4j
@RestController
@RequestMapping("/category")
@Api(tags = "分类相关接口")
public class CategoryController {
}
  • @ApiOperation用法如下:
@ApiOperation("添加菜品")
@CacheEvict(value = "categoryCache",allEntries = true)
@PostMapping
public R<String> addCategory(@RequestBody Category category) {
log.info("添加分类category{}", category);
categoryService.save(category);
return R.success("添加菜品分类成功");
}
  • @ApiImplicitParams、@ApiImplicitParam用法如下:
@ApiOperation("请求分页")
@Cacheable(value = "categoryCache",key = "#pageNum + '_' + #pageSize" )
@GetMapping("/page")
@ApiImplicitParams({
@ApiImplicitParam(name = "page",value = "页码",required = true),
@ApiImplicitParam(name = "pageSize",value = "每页记录数",required = true),
})
public R<Page> page(@RequestParam("page") Integer pageNum,
@RequestParam("pageSize") Integer pageSize) {
log.info("category分类分页");
Page<Category> categoryPageInfo = new Page<>(pageNum, pageSize);
LambdaQueryWrapper<Category> queryWrapper = new LambdaQueryWrapper<>();
queryWrapper.orderByAsc(Category::getSort);
categoryService.page(categoryPageInfo, queryWrapper);
return R.success(categoryPageInfo);
}
  • @ApiModel、@ApiModelProperty用法如下:
@Data
@ApiModel("分类")
public class Category implements Serializable {

private static final long serialVersionUID = 1L;

@ApiModelProperty("主键")
private Long id;

//类型 1 菜品分类 2 套餐分类
@ApiModelProperty("类型 1 菜品分类 2 套餐分类")
private Integer type;

//分类名称
@ApiModelProperty("分类名称")
private String name;

//顺序
@ApiModelProperty("顺序")
private Integer sort;
}

访问swagger-ui/index.html接口

https://localhost:8080/swagger-ui/index.html
http://localhost:8080/swagger-ui/index.html

image.png

二、使用knife4j生成接口UI

1、导入knife4j-spring-boot-starter依赖

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>

2、配置config

@Configuration
@EnableOpenApi
@Slf4j
public class SwaggerConfig extends WebMvcConfigurationSupport {

/**
* 设置静态资源映射
*/

@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
log.info("开始进行静态资源映射....");
registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30) // 选择文档类型 OpenApi 3.0
.apiInfo(apiInfo()) //配置swagger信息
.enable(true) // 是否开启 默认开启;
.groupName("reggie") // reggie
.select() // 选择
.apis(RequestHandlerSelectors.basePackage("com.xy.reggie.controller")) // 扫描的包路径下的类
.build(); // 创建
}

private ApiInfo apiInfo() {
return new ApiInfo(
"reggie 文档",
"reggie 文档",
"v1.0",
"https://www.xxx.edu.cn/",
new Contact("谢阳", "https://blog.51cto.com/learningfish", "xxxx@qq.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}

访问doc.html页面

https://localhost:8080/doc.html#/home 
http://localhost:8080/doc.html#/home

image.png

举报

相关推荐

0 条评论