Springfox生成的api-doc不与swagger-codegen一起工作。

Question

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

我使用来自春狐的引导-swagger模块，生成的api-doc如下所示(格式很好)

{
  "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规范。

我将代码粘贴到傲慢的编辑器中，它会抱怨很多错误，例如

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

那么，可以从Springfox生成的api-doc.json生成客户机代码吗？

Answer 1

在阅读了Springfox参考文档的文件之后，我解决了这个问题！

格式如下，因为在默认情况下，springfox应用RFC 6570

./categories{?categories} 

3.2。配置说明

这方面的一个例子是两个apis:首先，http://example.org/findCustomersBy?name=Test按名称查找客户。根据RFC 6570，这将表示为http://example.org/findCustomersBy{?name}。第二，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"
      }
    }

这份文件清楚地提到了昂首阔步的情况：

6.8.3.更改泛型类型的命名方式

默认情况下，带有泛型的类型将被标记为'\u00ab'(<<)、'\u00bb'(>>)和逗号。这可能是问题的事情，如昂首阔步-编码.您可以通过实现自己的GenericTypeNamingStrategy来覆盖此行为。例如，如果希望将列表编码为“ListOfString”，而Map被编码为“MapOfStringAndObject”，则可以在插件定制期间将forCodeGeneration自定义选项设置为true：

 docket.forCodeGeneration(true|false);

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

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