使用Swagger管理API

1.Swagger简介
2.在项目中使用Swagger
3.配置swagger
4.swagger配置扫描接口
5.配置API文档的分组
6.swagger的实体类扫描
7.给Controller加文档注释

1.Swagger简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

2.在项目中使用Swagger

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version>
</dependency><!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency><!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

Springfox 使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X +使用的是PathPatternMatcher，所以我们还需要修改一下SpringBoot配置文件内容：

新增如下配置：

spring:mvc:pathmatch:matching-strategy: ant_path_matcher

配置swagger 编写一个configure类：

@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {}

之后启动项目，访问如下地址，可以看到Swagger的初始化页面：

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

可以看到，我们编写的HelloController已经被Swagger扫描到了！

3.配置swagger

我们可以配置Swagger，实现基本页面的自定义：如下代码：

@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {// 配置了swagger的bean实例@Beanpublic Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}// 配置swagger信息 apiInfoprivate ApiInfo apiInfo() {Contact contact = new Contact("klza", "http://localhost:8080", "3390205563@qq.com");return new ApiInfo("klza","中国最大的网络安全服务商","1.0","imustctf.top",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}
}

效果：

4.swagger配置扫描接口

swagger默认会扫描全部路径下的API信息，我们可以进一步细化它的扫描范围：

需要对docket方法稍作改动：

例如：我们只想扫描controller包：

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.klza.controller")).build();
}

此时重启项目，error的API接口就扫描不到了！

5.配置API文档的分组

修改Docket中的groupName属性即可，若要配置多个组，就需要多个Docket：

先看看如何分组：

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("视频业务").select().apis(RequestHandlerSelectors.basePackage("com.klza.controller")).build();
}

重启项目，看到了分组情况：

配置多个分组，开启多个Docket即可：

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("视频业务").select().apis(RequestHandlerSelectors.basePackage("com.klza.controller")).build();
}@Bean
public Docket docket2() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("军火库业务");
}@Bean
public Docket docket3() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("竞赛业务");
}

6.swagger的实体类扫描

swagger很聪明，在controller中返回一个实体类对象，之后swagger就会在api中的model中生成一个实体类

例如：我们定义一个pojo类：

public class User {public String name;public String info;
}

在controller中使用它：

@GetMapping("/user")
public User user() {return new User();
}

重新启动项目，在model中会生成对应的实体类信息：

这还不够！我们还可以给实体类及其字段增加文档注释：

@ApiModel("用户实体类") // 给类加一个api注释
public class User {@ApiModelProperty("名字") // 给字段加一个api注释public String name;@ApiModelProperty("个人简介")public String info;
}

重启项目，看看效果：

7.给Controller加文档注释

给一个controller的方法加注释，使用@ApiOperation("xxx")：

@RestController
public class HelloController {@ApiOperation("Hello控制类")@GetMapping("/hello")public String hello() {return "hello";}@ApiOperation("获得一个user")@GetMapping("/user")public User user() {return new User();}
}

还可以给参数加文档注释：

public String hello(@ApiParam("用户名") String username){return "hello";
}

使用Swagger管理API相关推荐

Spring Boot 整合Swagger实现API管理
Spring Boot 整合Swagger实现API管理 1 Swagger介绍根据官网的介绍: https://swagger.io Swagger 是一款RESTFUL接口的.基于YAML.JS ...
ABP学习实践(五)--引入Swagger对API接口进行管理
以目前流行的前后端分离模式来看,ABP框架更适用于后端开发,而对API接口的管理就成了一项必不可少的功能. 1.安装Swashbuckle.AspNetCore 使用Nuget管理器在分布式服务层和展 ...
spring boot 集成springfox，使用swagger对 API 接口进行测试管理的 demo 示例
1. 描述一个springboot项目集成 springfox 3.0,使用swagger对 API 接口进行测试管理的 demo示例. 环境: IDE(idea):2021.3 JDK:1.8 m ...
SpringBoot整合Swagger测试api构建
@Author:SimpleWu 什么是Swagger? Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspec ...
Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api（二十）
一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目实现了与SpingMVC框架的无缝集成功能,方便生成spring r ...
multipartfile前端怎么传_前端那些事如何更好管理 Api 接口
❝ 前沿:自从前端和后端分家之后,前后端接口对接就成为了家常,"谁"也离不开谁,而对接接口的过程就离不开接口文档,比较主流就是Swagger(强大的API文档工具),当然今天它不是 ...
基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档(上篇)
前言为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...
ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
引言在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...
【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...

使用Swagger管理API

使用Swagger管理API

1.Swagger简介

2.在项目中使用Swagger

3.配置swagger

4.swagger配置扫描接口

5.配置API文档的分组

6.swagger的实体类扫描

7.给Controller加文档注释

使用Swagger管理API相关推荐

最新文章

热门文章