Spring Boot之Swagger 3.0

最新推荐文章于 2024-06-03 08:30:00 发布

月半花开

最新推荐文章于 2024-06-03 08:30:00 发布

阅读量2.2k

点赞数 2

文章标签： spring boot 后端 java

本文链接：https://blog.csdn.net/qq_20957669/article/details/121914479

版权

第一步：添加Swagger3自定义配置类（可选）

前言

这是一个突破性的变更

有关此项目的更多信息，请访问API Documentation & Design Tools for Teams | Swagger

什么是Swagger

Swagger 是最流行的 API 开发工具

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：

Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

有用的链接

项目集成

本文将通过几个简单步骤教大家如何集成Swagger3

共三个步骤，步骤如下：

1、添加依赖

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

2、启动类配置

@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

@EnableOpenApi这个注解文档解释如下：

Indicates that Swagger support should be enabled.
This should be applied to a Spring java config and should have an accompanying '@Configuration' annotation.
Loads all required beans defined in @see SpringSwaggerConfig

只有在配置类标注了@EnableOpenApi这个注解才会生成Swagger文档

3、添加配置类启动项目


import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
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;


@EnableOpenApi
@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Bean public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()).build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui 示例 APIs")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact(new Contact("拾一", "http://localhost:8080/swagger-ui/index.html", "314569024@qq.com"))
                .version("1.0")
                .build();
    }


}

访问：http://localhost:8080/swagger-ui/index.html

一个简单的Swagger后台接口文档，至此就搭建完成了。

可以看到，上面那个界面中，默认显示了一个basic-error-controller接口分组，但是我们并没有写；

通过在项目中查找我们发现，SpringBoot内部确实有这样一个控制器类，如下所示

说明Swagger默认的配置，会自动把@Controller控制器类添加到接口文档中

在`Docket`中的方法`globalRequestParameters()`可以设置公共的请求参数，接收的参数是一个`List<RequestParameter>`，因此只需要构建一个`RequestParameter`集合即可，如下：

@Bean
public Docket frontApi() {
   //构建一个公共请求参数platform，放在在header
   RequestParameter parameter = new RequestParameterBuilder()
      //参数名称
      .name("platform")
      //描述
      .description("请求的平台")
      //放在header中
      .in(ParameterType.HEADER)
      //是否必传
      .required(true)
      .build();
      //构建一个请求参数集合
      List<RequestParameter> parameters = Collections.singletonList(parameter);
        return new Docket(DocumentationType.OAS_30)
                .....
                .build()
                .globalRequestParameters(parameters);
    }