SpringDoc和Swagger使用示例详解_Java

swagger和springdoc是两个常用的工具，用于生成和维护api文档，特别是针对基于rest的web服务。它们有效地提升了api的可读性和可维护性，帮助开发者、产品经理和其他利益相关者更好地理解和使用所提供的api。

注意：swagger支持springboot2.0但不支持springboot3.0

一、springdoc

springdoc是一个开源的库，旨在将spring boot项目的restful api与openapi 3文档生成器集成。springdoc与spring boot应用无缝集成，并支持包括swagger ui在内的多种用户界面。

1.添加依赖

    <dependencies>
        <dependency>
            <groupid>org.springdoc</groupid>
            <artifactid>springdoc-openapi-starter-webmvc-ui</artifactid>
            <version>2.6.0</version>
        </dependency>
    </dependencies>

2.配置代码

添加一个配置类，并添加xml配置

配置解释

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationssorter: method
    tagssorter: alpha

（1）springdoc.api-docs.path

属性路径:springdoc.api-docs.path

作用: 定义 openapi 文档的访问路径。

默认值:/v3/api-docs

示例:

springdoc:
  api-docs:
    path: /v3/api-docs

配置后，api 文档可以通过http://<host>:<port>/v3/api-docs访问。

（2）springdoc.swagger-ui.path

属性路径:springdoc.swagger-ui.path
作用: 定义 swagger ui 的访问路径。
默认值:/swagger-ui.html
示例:

springdoc:
  swagger-ui:
    path: /swagger-ui.html

配置后，swagger ui 可以通过http://<host>:<port>/swagger-ui.html访问。

（3）springdoc.swagger-ui.operationssorter

属性路径:springdoc.swagger-ui.operationssorter
作用: 定义如何对 swagger ui 中的操作进行排序。
可选值:
- alpha: 按照操作名称的字母顺序排列。
- method: 按照 http 方法进行排序（如 get, post, put, delete）。
示例:

springdoc:
  swagger-ui:
    operationssorter: method

配置后，操作会按照 http 方法的顺序显示。

（4）springdoc.swagger-ui.tagssorter

属性路径:springdoc.swagger-ui.tagssorter
作用: 定义如何对 swagger ui 中的标签进行排序。
可选值:
- alpha: 按照标签名称的字母顺序排列。
示例:

springdoc:
  swagger-ui:
    tagssorter: alpha

配置后，标签会按照字母顺序显示。

（5）springdoc.title

属性路径:springdoc.title
作用: 设置整个 api 文档的标题。
示例:

springdoc:
  title: 用户管理

配置后，生成的 api 文档的标题会显示为“用户管理”。

使用

package com.ck.framework.common.springdoc.config;
import io.swagger.v3.oas.models.openapi;
import io.swagger.v3.oas.models.info.contact;
import io.swagger.v3.oas.models.info.info;
import org.springframework.beans.factory.annotation.autowired;
import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
/**
 * @classname springdocconfig
 * @description
 * @author 
 * @date 2024/8/28 15:55
 * @version 1.0
 */
@configuration
public class springdocconfig {
    @autowired
    private baseconfig baseconfig;
    @bean
    public openapi createopenapi() {
        return new openapi()
                .info(createinfo());
    }
    private info createinfo() {
        return new info()
                .contact(createcontact())
                .title(baseconfig.gettitle())
                .description(baseconfig.getdescription())
                .version(baseconfig.getversion());
    }
    private contact createcontact() {
        contact contact = new contact();
        contact.name(baseconfig.getcontactname());
        contact.url(baseconfig.getcontacturl());
        contact.email(baseconfig.getcontactemail());
        return contact;
    }
}

3.控制器处理

需要再controller里面加上tag注解

package com.ck.framework.user.controller;
import com.ck.framework.common.web.bean.result;
import com.ck.framework.user.entity.pageresult;
import com.ck.framework.user.entity.dto.userdto;
import com.ck.framework.user.entity.po.userpo;
import com.ck.framework.user.entity.req.userlistreq;
import com.ck.framework.user.entity.req.userreq;
import com.ck.framework.user.service.userservice;
import io.swagger.v3.oas.annotations.tags.tag;
import org.springframework.beans.factory.annotation.autowired;
import org.springframework.web.bind.annotation.*;
/**
 * @classname usercontroller
 * @description
 * @author 
 * @date 2024/8/24 0:03
 * @version 1.0
 */
@restcontroller
@requestmapping("/user")
@tag(name = "用户管理")
public class usercontroller {
    @autowired
    private userservice userservice;
    @postmapping
    public result<boolean> adduser(@requestbody userreq userreq) {
        userdto userdto = new userdto();
        userdto.setname(userreq.getname());
        userdto.setage(userreq.getage());
        int num = userservice.adduser(userdto);
        if (num > 0) {
            return result.success(true);
        } else {
            return result.fail();
        }
    }
    @deletemapping("/{id}")
    public result<boolean> deleteuser(@requestbody userreq userreq) {
        userdto userdto = new userdto();
        userdto.setid(userreq.getid());
        int num = userservice.deluser(userdto);
        if (num > 0) {
            return result.success(true);
        } else {
            return result.fail();
        }
    }
    @getmapping
    public result<pageresult<userpo>> getuserpage(@requestbody userlistreq userlistreq) {
        userdto userdto = new userdto();
        userdto.setpageindex(userlistreq.getpageindex());
        userdto.setpagesize(userlistreq.getpagesize());
        pageresult<userpo> pageresult = userservice.getuserpage(userdto);
        return result.success(pageresult);
    }
}

4.访问

5.优点

无缝集成:
- 专为 spring boot 设计，非常容易集成到 spring boot 应用中。
减少注解:
- 可以自动解析 spring mvc 或 spring webflux 控制器，减少了需要添加的注解数量。
自动化配置:
- 大量依赖默认配置，无需复杂的手动配置，开箱即用。
支持最新技术:
- 支持 spring boot 2.x 及更高版本，跟进 spring 生态系统的最新发展。
丰富的文档和示例:
- 提供了良好的文档和示例，帮助开发者快速上手。

6.缺点

局限性:
- 专门面向 spring boot 项目，不适用于其他框架或原生 spring 项目。
功能相对简单:
- 相对于 swagger 提供的完整工具链，springdoc 的功能相对单一，主要聚焦于文档生成。

二、swagger

swagger是一个用于生成、描述、调用和可视化 restful web 服务的开源框架。它的核心是一个名为 openapi 规范的描述性语言。swagger 是 java 应用程序中常用的工具之一，因为它能自动生成 api 文档，并提供一个用户友好的接口来测试 api。

在 java 项目中使用 swagger 通常包括以下步骤：

1. 添加依赖项

首先，你需要在你的项目中添加所需的 swagger 依赖项。以 maven 项目为例，在pom.xml文件中添加以下依赖：

    <dependencies>
        <dependency>
            <groupid>io.springfox</groupid>
            <artifactid>springfox-swagger-ui</artifactid>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupid>io.springfox</groupid>
            <artifactid>springfox-swagger2</artifactid>
            <version>3.0.0</version>
        </dependency>
    </dependencies>

2. 配置 swagger

添加一个 swagger 配置类。例如，在 spring boot 应用程序中，你可以添加以下内容：

package com.ck.framework.common.swagger.config;
import org.springframework.context.annotation.configuration;
import springfox.documentation.builders.apiinfobuilder;
import springfox.documentation.builders.pathselectors;
import springfox.documentation.builders.requesthandlerselectors;
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;
/**
 * @classname swaggerconfig
 * @description 配置swagger的类，启用swagger并定义api文档的相关信息
 * @author 
 * @date 2024/8/28 08:31
 * @version 1.0
 */
@configuration  // 表示这是一个配置类
@enableswagger2  // 启用swagger2
public class swaggerconfig {
    /**
     * 创建一个docket bean，用于配置swagger的核心内容，包括哪些包中的api需要生成文档和api的基本信息。
     *
     * @return docket对象，用于swagger的配置
     */
    public docket createrestapi() {
        return new docket(documentationtype.swagger_2)  // 指定文档类型为swagger2
                .apiinfo(apiinfo())  // 配置api信息
                .select()  // 返回一个apiselectorbuilder实例，用于控制哪些接口暴露给swagger
                .apis(requesthandlerselectors.basepackage("com.ck.framework.common.swagger"))  // 选择扫描的包名
                .paths(pathselectors.ant("/*"))  // 选择哪些路径的api需要生成文档
                .build();  // 构建docket实例
    }
    /**
     * 构建api基本信息，用于页面展示的文档信息。
     *
     * @return apiinfo对象，包含相关api的描述信息
     */
    public apiinfo apiinfo() {
        return new apiinfobuilder()
                .title("")  // 设置文档标题
                .description(" 测试swagger")  // 设置文档描述信息
                .contact(new contact("", "git地址", "zhuchb_0509@163.com"))  // 设置联系人信息
                .version("1.0")  // 设置文档版本
                .build();  // 构建apiinfo实例
    }
}

3. 将注释添加到控制器中

使用 swagger 注释描述注册到controller。例如：

package com.ck.framework.user.controller;
import com.ck.framework.common.web.bean.result;
import com.ck.framework.user.entity.pageresult;
import com.ck.framework.user.entity.dto.userdto;
import com.ck.framework.user.entity.po.userpo;
import com.ck.framework.user.entity.req.userlistreq;
import com.ck.framework.user.entity.req.userreq;
import com.ck.framework.user.service.userservice;
import io.swagger.annotations.api;
import org.springframework.beans.factory.annotation.autowired;
import org.springframework.web.bind.annotation.*;
/**
 * @classname usercontroller
 * @description
 * @author 
 * @date 2024/8/24 0:03
 * @version 1.0
 */
@restcontroller
@requestmapping("/user")
@api(value = "用户管理")
public class usercontroller {
    @autowired
    private userservice userservice;
    @postmapping
    public result<boolean> adduser(@requestbody userreq userreq) {
        userdto userdto = new userdto();
        userdto.setname(userreq.getname());
        userdto.setage(userreq.getage());
        int num = userservice.adduser(userdto);
        if (num > 0) {
            return result.success(true);
        } else {
            return result.fail();
        }
    }
    @deletemapping("/{id}")
    public result<boolean> deleteuser(@requestbody userreq userreq) {
        userdto userdto = new userdto();
        userdto.setid(userreq.getid());
        int num = userservice.deluser(userdto);
        if (num > 0) {
            return result.success(true);
        } else {
            return result.fail();
        }
    }
    @getmapping
    public result<pageresult<userpo>> getuserpage(@requestbody userlistreq userlistreq) {
        userdto userdto = new userdto();
        userdto.setpageindex(userlistreq.getpageindex());
        userdto.setpagesize(userlistreq.getpagesize());
        pageresult<userpo> pageresult = userservice.getuserpage(userdto);
        return result.success(pageresult);
    }
}

4. 访问 swagger ui

启动你的 spring boot 应用程序后，打开浏览器访问http://localhost:8080/swagger-ui.html，你会看到自动生成的 api 文档及其用户界面。

5.优点

工具链完备:
- swagger 提供了全面的工具，包括 swagger editor、swagger codegen 和 swagger ui，这些工具可以涵盖从开发到文档化的各个环节。
广泛支持:
- 被多个语言和框架广泛支持，几乎成为业界标准。
丰富的插件和社区支持:
- 有大量的插件和扩展，可以满足各种自定义需求。
可视化交互:
- swagger ui 提供了极为友好的界面，允许开发者甚至非技术人员进行直接的api测试与调用。