问题：

Springfox生成的api文档不能与swagger codegen一起使用

石思淼

2023-03-14

我正在测试是否可以使用springfox生成的api文档通过swagger codegen生成Java客户机代码。

我使用springfox演示中的boot-swagger模块，生成的api文档如下所示（格式非常好）

{
  "swagger": "2.0",
  "info": {
    "description": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
    "version": "2.0",
    "title": "Springfox petstore API",
    "termsOfService": "http://springfox.io",
    "contact": {
      "name": "springfox"
    },
    "license": {
      "name": "Apache License Version 2.0",
      "url": "https://github.com/springfox/springfox/blob/master/LICENSE"
    }
  },
  "host": "localhost:8080",
  "basePath": "/springfox",
  "tags": [
    {
      "name": "category-controller",
      "description": "Category Controller"
    }
  ],
  "paths": {
    "/categories{?categories}": {
      "post": {
        "tags": [
          "category-controller"
        ],
        "summary": "map",
        "operationId": "mapUsingPOST",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "categories",
            "in": "query",
            "description": "categories",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "collectionFormat": "multi"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "ONE",
                  "TWO",
                  "THREE"
                ]
              }
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/category/Resource{?someEnum}": {
      "get": {
        "tags": [
          "category-controller"
        ],
        "summary": "search",
        "operationId": "searchUsingGET",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "someEnum",
            "in": "query",
            "description": "someEnum",
            "required": true,
            "type": "string",
            "enum": [
              "ONE",
              "TWO",
              "THREE"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "string"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/category/map": {
      "get": {
        "tags": [
          "category-controller"
        ],
        "summary": "map",
        "operationId": "mapUsingGET",
        "produces": [
          "*/*"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/definitions/Pet"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/category/{id}": {
      "post": {
        "tags": [
          "category-controller"
        ],
        "summary": "someOperation",
        "operationId": "someOperationUsingPOST",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "id",
            "required": true,
            "type": "integer",
            "format": "int64"
          },
          {
            "in": "body",
            "name": "userId",
            "description": "userId",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/category/{id}/map{?test}": {
      "post": {
        "tags": [
          "category-controller"
        ],
        "summary": "map",
        "operationId": "mapUsingPOST_1",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "id",
            "required": true,
            "type": "string"
          },
          {
            "name": "test",
            "in": "query",
            "description": "test",
            "required": true,
            "items": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/category/{id}/{userId}": {
      "post": {
        "tags": [
          "category-controller"
        ],
        "summary": "ignoredParam",
        "operationId": "ignoredParamUsingPOST",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "id",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    }
  },
  "definitions": {
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      },
      "title": "Category"
    },
    "Map«string,Pet»": {
      "type": "object",
      "title": "Map«string,Pet»",
      "additionalProperties": {
        "$ref": "#/definitions/Pet"
      }
    },
    "Pet": {
      "type": "object",
      "properties": {
        "category": {
          "$ref": "#/definitions/Category"
        },
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "identifier": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        },
        "photoUrls": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "status": {
          "type": "string",
          "description": "pet status in the store",
          "allowEmptyValue": false,
          "enum": [
            "available",
            "pending",
            "sold"
          ]
        },
        "tags": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Tag"
          }
        }
      },
      "title": "Pet"
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      },
      "title": "Tag"
    }
  }
}

代码生成失败，看起来api-doc.json甚至不适合swagger规范。

我将代码粘贴到了swagger编辑器中，它抱怨了很多错误，例如

Semantic error at paths./categories{?categories} 
Query strings in paths are not allowed.
Jump to line 18

那么，是否可以从Springfox生成的api-doc.json生成客户端代码呢？

共有1个答案

高云瀚

2023-03-14

在阅读了Springfox参考文档后，我已经解决了这个问题！

下面这样的格式是因为默认情况下springfox应用RFC6570

./categories{?categories}

这方面的一个例子是两个api：首先，http://example.org/findCustomersBy?name=Test按名称查找客户。根据RFC 6570，这将表示为http://example.org/findCustomersBy{？名称}.第二，http://example.org/findCustomersBy?zip=76051通过拉链找到客户。根据RFC 6570，这将表示为http://example.org/findCustomersBy{？zip}.

还有一个问题我在问题中没有提到：

    "Map«string,Pet»": { // The generated JSON contains special characters
      "type": "object",
      "title": "Map«string,Pet»",
      "additionalProperties": {
        "$ref": "#/definitions/Pet"
      }
    }

该文件明确提到了昂首阔步的codegen情况：

默认情况下，带有泛型的类型将标记为“\u00ab”(

 docket.forCodeGeneration(true|false);

总之，当我们在springfox中为swagger codegen生成摘要时，我们需要指定以下开关：

new Docket(DocumentationType.SWAGGER_2)
                .forCodeGeneration(true)
                .enableUrlTemplating(false)

类似资料：

springfox 2.2.2未生成API文档

我正致力于将Springfox 2.2.2整合到我的Spring MVC项目中，但是没有像我所说的那样生成API文档。下面是关于我的配置的一些信息。我已经提供了以下依赖项（以及其他库，如fasterxml、WebJar、正确版本的spring等） Springfox的配置如下：示例性控制器如下所示：使用上面的设置，当我执行URL:localserver:8080/myapp/swagger-
springfox(swagger2)不能与GsonHttpMessageConverterConfig一起工作

我试图构建的是一个spring-boot(V1.2.3)应用程序，并使用SpringFox(swagger2)V2.0.0公开我的Rest API 我的大摇大摆的Spring配置以下是如果不使用: 有没有一个解决方案来创建一个正确的、没有价值和逃避的大摇大摆的JSON？
Swagger API 文档生成

支持在项目中使用 Swagger 注解语法，运行命令，生成 Swagger 文件。 Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。 Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。 Swagger 是一种通用的，和编程语言无关的 API 描述规范。 imi-
阐述使用ant生成REST API文档

我正试图集成Enunicate来生成我们现有的API的REST文档。我得到一个警告“警告:未知工件‘文档’。不会导出工件。当执行ant任务时。我的设置中是否缺少什么？ .xml的解释是：相关的蚂蚁片段是: 谢谢。维努
使用OpenAPI Maven插件生成API文档

不幸的是，SpringFox还不支持OpenAPI3，而且，当我只想将最初的yaml公开为JSON时，使用基于反射的生成器似乎毫无意义。
生成REST API的Swagger UI文档

问题内容：我有使用Java的JAX-RS / Jersey开发的REST API。我想为其转换/生成基于Swagger的UI文档。有人可以简单的方式告诉我精确的步骤吗？很抱歉，他们网站上的步骤对我来说并不清楚。问题答案：有几种方法可以将swagger-core与您的应用程序集成，但是根据您的描述，我将按照https://github.com/swagger- api/swagger-core

Springfox生成的api文档不能与swagger codegen一起使用

共有1个答案

相关问答

相关文章

相关阅读

相关工具

相关文档