概述
关于swagger的描述,博客一大堆。
这里简单描述一下,swagger是一个可以动态生成符合Open API规范的接口API文档。
使用Swagger的好处:
- 不需要开发人员特意去写。
- 统一某一项目的前后端API文档。
Swagger工具包含多个组件。本文中主要是使用Swagger-UI组件。
Swagger-UI组件是将Open API规范呈现为交互式API文档。简而言之就是,Swagger-UI既可以作为API文档,也能够对API进行调试。
快速入门
- 创建SpringBoot项目,并确保项目能够正确运行。
- 导入相关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>
- 编写Swagger配置类
@Configuration //标注当前为配置类
@EnableSwagger2 //开启Swagger
public class SwaggerConf {
}
- 启动SpringBoot项目,并访问
http://localhost:8080/swagger-ui.html
。看到下图界面,表示Swagger已经和SpringBooot整合成功。接下来需要做的就是更加自己的需求对Swagger进行相关的配置。
如果你在启动项目的时候遇到这个问题,请访问该链接解决方案
org.springframework.hateoas.config.HateoasConfiguration required a single bean, but 15 were found:
配置Swagger
在SpringBoot中,对Swagger的配置都是通过配置Docket对象来实现的。
配置扫描接口
有时候我们只是需要当前项目中部分API的信息,因此我们就需要进行相关的配置,只获取我们所需要的那些API信息。
Swagger中,在创建Docket对象时,通过select()
方法来配置扫描哪些接口。
整个过程可以用一个词来概括—>层层细化
例子:
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
/* 扫描接口配置 */
.select()
.apis(RequestHandlerSelectors.basePackage("run.halo.app.controller.content.api"))
.paths(PathSelectors.ant("/api/content/**"))
.build();
/* 扫描接口配置 */
}
在上述代码中,主要是通过以下三个方法来进行扫描接口配置的:
- selcet():是创建一个构造器,用于定义Swagger生成的文档中应该包含哪些接口和方法。
- api():用来定义要包含的类(控制器和模型类)。
- paths():根据请求路径定义当前Docket需要包含控制器的哪些方法。
下面对这三个方法进行详细解释
select()
源码如下:
/**
* Initiates a builder for api selection.
*
* @return api selection builder. To complete building the api selector, the build method of the api selector
* needs to be called, this will automatically fall back to building the docket when the build method is called.
*/
public ApiSelectorBuilder select() {
return new ApiSelectorBuilder(this);
}
该方法返回了一个构造器ApiSelectorBuilder
,用于构建API选择器ApiSelector
。
在该构造器中,比较常用的两个方法是apis()
和paths()
。
apis()
源码如下
public ApiSelectorBuilder apis(Predicate<RequestHandler> selector