api-doc, созданный Springfox, не работает с swagger-codegen

Я тестирую, могу ли я использовать api-doc, созданный springfox, для генерации клиентского кода Java через swagger-codegen.

Я использую модуль boot-swagger из springfox-demos, и сгенерированный 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.

Я вставил код в редактор swagger, и он жалуется на множество ошибок, таких как

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

Так можно ли сгенерировать клиентский код из api-doc.json, созданного Springfox?


person Bai Bing    schedule 14.01.2019    source источник
comment
не могли бы вы включить свое определение /categories конечной точки?   -  person JoSSte    schedule 16.01.2019
comment
Спасибо за ваш ответ! Это просто пример, фактически сгенерированный YAML очень большой, и если мне придется вручную изменить ошибки внутри этого YAML, это будет слишком утомительно. Я предполагаю, что это всего лишь ограничение Springfox, нужно смириться с этим и забыть о создании клиента из YAML.   -  person Bai Bing    schedule 16.01.2019
comment
Я думаю, что ваше определение неверно. Если вы свяжете аннотации из метода, определяющего конечную точку, мы сможем исправить это   -  person JoSSte    schedule 16.01.2019


Ответы (1)


Прочитав документ Справочная документация Springfox, я решил эту проблема!

Формат, как показано ниже, потому что по умолчанию springfox применяет RFC 6570

./categories{?categories} 

3.2. Конфигурация объяснена

Примером этого могут быть два API: во-первых, http://example.org/findCustomersBy?name=Test, чтобы найти клиентов по имени. Согласно RFC 6570 это будет представлено как http://example.org/findCustomersBy {? Name}. Во-вторых, http://example.org/findCustomersBy?zip=76051 для поиска клиентов с помощью zip-архива. . Согласно 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' (>>) и запятыми. Это может быть проблематично с такими вещами, как swagger-codegen. Вы можете переопределить это поведение, реализовав свою собственную GenericTypeNamingStrategy. Например, если вы хотите, чтобы List был закодирован как ListOfString, а Map - как MapOfStringAndObject, вы можете установить для параметра настройки forCodeGeneration значение true во время настройки плагина:

 docket.forCodeGeneration(true|false);

Подводя итог, когда мы генерируем docket в springfox для swagger-codegen, нам нужно указать следующие переключатели:

new Docket(DocumentationType.SWAGGER_2)
                .forCodeGeneration(true)
                .enableUrlTemplating(false)
person Bai Bing    schedule 17.02.2019