SpringBoot整合Swagger3生成接口文档

最新推荐文章于 2024-09-13 22:21:16 发布

小舟同学

最新推荐文章于 2024-09-13 22:21:16 发布

阅读量540

点赞数

分类专栏： Java开发文章标签： spring boot java

本文链接：https://blog.csdn.net/qq_44021875/article/details/116199409

版权

Java开发专栏收录该内容

5 篇文章 0 订阅

订阅专栏

SpringBoot整合Swagger3生成接口文档

一、Swagger简介
- Swagger官网提供的开源工具：
- Spring提供的Springfox Swagger：
二、SpringBoot整合Swagger3步骤：

一、Swagger简介

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，后来成为了 Open API 标准的主要定义者。Swagger 提供了一套通过代码和注解自动生成文档的方法，对于保证API 文档的及时性将有很大的帮助。
Swagger2：17年停止维护
Swagger3（Open Api3）：17年发布

Swagger官网提供的开源工具：

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中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

Spring提供的Springfox Swagger：

可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件

二、SpringBoot整合Swagger3步骤：

1.pom.xml文件中引入Swagger3依赖

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

2.编写Swagger3Config配置类

package com.example.swaggerDemo.util;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
 * @Author 小舟同学
 * @Date 2021/4/26 17:35
 * @Description 说明：Swagger3Config的配置
 */

//@EnableSwagger2 是 swagger2.0版本的注解
//swagger在3.0之后换成了@EnableOpenApi
@Configuration
@EnableOpenApi//开启Swagger3
public class Swagger3Config {

    @Bean
    public Docket createRestApi(){
        //swagger设置，基本信息，要解析的接口及路径等
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//设置扫描路径 //设置通过什么方式定位需要自动生成文档的接口，这里定位方法上的@ApiOperation注解
                .paths(PathSelectors.any())接口URI路径设置，any是全路径，也可以通过PathSelectors.regex()正则匹配
                .build();
    }
    //生成接口信息，包括标题、联系人，联系方式等
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("适用于前后端分离统一的接口文档")
                .version("1.0")
                .build();
    }

}

3.Swagger注解的使用说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · div（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性

4.Controller层的配置(Swagger3注解使用位置举例）

package com.example.swaggerDemo.controller;


import com.example.swaggerDemo.bean.JsonBean;
import com.example.swaggerDemo.service.IyunhuService;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author 小舟同学
 * @Date 2021/4/23 13:57
 * @Description 说明：测试Swagger注解使用
 */
@Api(tags = "测试接口文档类")
@RestController
@RequestMapping("/test")
public class TestController {
    private static final Logger logger = LoggerFactory.getLogger(TestController.class);

    @Autowired
    IyunhuService service;

    @ApiOperation("转账")
    @PostMapping("/transfer")
    public Object transfer(JsonBean json) throws Exception{
        return service.transfer(json);
    };

    @ApiOperation("转账查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "payexacctno", value = "企业账号", dataType = "String", required = true),
            @ApiImplicitParam(name = "payexacctname", value = "企业户名", dataType = "String", required = true),
            @ApiImplicitParam(name = "orderid", value = "订单号", dataType = "String", required = true),
    })
    @PostMapping("/transferQuery")
    public Object transferQuery(JsonBean json) throws Exception{
        return service.transferQuery(json);
    };

}