Swagger基本配置及常用注解

概述

关于swagger的描述，博客一大堆。

这里简单描述一下，swagger是一个可以动态生成符合Open API规范的接口API文档。

使用Swagger的好处：

• 不需要开发人员特意去写。
• 统一某一项目的前后端API文档。

Swagger工具包含多个组件。本文中主要是使用Swagger-UI组件。
Swagger-UI组件是将Open API规范呈现为交互式API文档。简而言之就是，Swagger-UI既可以作为API文档，也能够对API进行调试。

快速入门

1. 创建SpringBoot项目，并确保项目能够正确运行。
2. 导入相关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>

3. 编写Swagger配置类

@Configuration	//标注当前为配置类
@EnableSwagger2	//开启Swagger
public class SwaggerConf {
   
}

4. 启动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) {