若依自定义服务配置swagger文档

最新推荐文章于 2025-10-05 03:58:18 发布

原创最新推荐文章于 2025-10-05 03:58:18 发布 · 3.5k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#postman #eureka #java

java 专栏收录该内容

55 篇文章

订阅专栏

本文介绍如何在Swagger中调试自定义接口。通过分析源码并在GatewayProperties中添加配置，然后在Nacos中更新设置，可以实现Swagger-UI的自定义。推荐使用第三方维护的UI，它提供更清晰的注释和更人性化的文档。此外，还需要在自定义服务的pom.xml、主类和Nacos配置中进行相应调整，并在接口方法和入参上添加注释。完成这些步骤后，将能在Swagger界面上看到自定义服务的接口文档。

我们想要在swagger中直接调试自己的接口

通过分析源码可得具体添加 spec的代码如下在gatewayProperties这个对象中

package com.ruoyi.gateway.config;
/**
 * 聚合系统接口
 * 
 * @author ruoyi
 */
@Component
public class SwaggerProvider implements SwaggerResourcesProvider
{
    @Override
    public List<SwaggerResource> get()
    {
        List<SwaggerResource> resourceList = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        // 获取网关中配置的route
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        gatewayProperties.getRoutes().stream()

这个对象需要在网关的nacos配置中增加如下代码

spring:
  cloud:
    gateway:
      routes:
        # APP模块
        - id: ruoyi-app
          uri: lb://ruoyi-app
          predicates:
            - Path=/app/**
          filters:
            - StripPrefix=1

网关中默认配置了 swagger-Ui


        <!-- 官方 Swagger UI 3.0 -->
        <!--        <dependency>-->
        <!--            <groupId>io.springfox</groupId>-->
        <!--            <artifactId>springfox-swagger-ui</artifactId>-->
        <!--            <version>${swagger.fox.version}</version>-->
        <!--        </dependency>-->

        <!-- 第三方 Swagger UI 被淘汰了 启用SwaggerBootstrapUi提供的增强功能 后会空白! -->
<!--        <dependency>-->
<!--            <groupId>com.github.xiaoymin</groupId>-->
<!--            <artifactId>swagger-bootstrap-ui</artifactId>-->
<!--            <version>1.9.6</version>-->
<!--        </dependency>-->

        <!--  第三方 swaggerUi https://gitee.com/xiaoym/knife4j  -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-ui</artifactId>
            <version>2.0.9</version>
        </dependency>


        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.fox.version}</version>
        </dependency>

官方3.0地址是 127.0.0.1:8080/swagger-ui/index.html

推荐使用 第三方维护的ui替换官方ui 注释更清晰文档更人性

新ui地址为 127.0.0.1:8080/doc.html


        <!-- Swagger UI -->
<dependency>
      <groupId>com.github.xiaoymin</groupId>
     <artifactId>swagger-bootstrap-ui</artifactId>
     <version>1.9.6</version>
</dependency>

自定义服务的 pom.xml 中增加


        <!-- RuoYi Common Swagger -->
        <dependency>
            <groupId>com.ruoyi</groupId>
            <artifactId>ruoyi-common-swagger</artifactId>
        </dependency>

在自定义服务的main主类中增加

...

/**
 *  开启swagger
 */
@EnableCustomSwagger2

public class MyAppApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyAppApplication.class, args);
        ...

在自定义服务的nacos的配置中增加


# swagger配置
swagger:
  title: app模块接口文档
  license: Powered By kalun
  licenseUrl: https://www.apizza.net/project/7eca0397c4b96fcaa115be0ee654c9c6/browse

在定义的接口中注释方法


    @ApiOperation(value = "将参数转换为JSON", notes = "")

入参参数添加注释


    @ApiParam(value = "版本号ApiParam", defaultValue = "2")

最终效果

第三方ui效果