Блог

Главная - Вопросы по программированию - Недопустимая спецификация Swagger: спецификация swagger в «swagger.yml» недопустима для спецификации swagger 2.0

Недопустимая спецификация Swagger: спецификация swagger в «swagger.yml» недопустима для спецификации swagger 2.0

#swagger #swagger-2.0 #go-swagger

#swagger #swagger-2.0 #go-swagger

Вопрос:

Я пытаюсь использовать Swagger. Ниже swagger.yml приведен файл.

 swagger: "2.0"
basePath: /myapp/api
info:
  description: My description
  title: My title
  version: 0.1.0
produces:
  - application/json
consumes:
  - application/json
schemes:
  - http
paths:
  /contract:
    get:
      operationId: "Get contract"
      description: Get information
      parameters:
        - in: path
          name: contractId
            description: ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Information...
          schema:
            $ref: "#/definitions/contract"
        404:
          description: "Not found."
    post:
      operationId: "Create"
      parameters:
        - in: body
          name: contractId
          schema:
            $ref: '#/definitions/requestBodies/contract'
      responses:
        200:
          description: Success...
        400:
          description: Problem...
definitions:
  contract:
    title: Contract
    type: object
    properties:
      name:
        title: Name
        type: string
      services:
        title: Services
        type: array
        items:
          title: Service
          $ref: '#/definitions/service'
      xyz:
        title: Xyz
        $ref: '#/definitions/virtualMachine'
  service:
    title: Service
    type: object
    properties:
      containerName:
        title: ContainerName    
        type: string
      ...
      contracts:
        title: Contracts
        type: array
        items:
          title: Contract
          $ref: '#/definitions/contract'    
  xyz:
    title: Xyz 
    type: object
    properties:
      serverId:
        title: ServerID
        type: string
      contractId:
        title: ContractID
        type: uuid  
      ...  
  requestBodies:
    contract:
      content:
        application/json:
          schema:
            $ref: '#/definitions/contract'

Когда я пытаюсь сгенерировать документацию, я получаю следующую ошибку:

 swagger generate server -f swagger.yml 
2020/10/26 15:43:31 validating spec /home/dalton/workspace/.../.../swagger.yml
The swagger spec at "/home/dalton/workspace/.../.../swagger.yml" is invalid against swagger specification 2.0. see errors :
- definitions.requestBodies.contract in body is a forbidden property
- "definitions.xyz.properties.contractId.type" must validate at least one schema (anyOf)
- definitions.xyz.properties.contractId.type in body must be of type array: "string"

Что я делаю не так?

Комментарии:

1. Ваше определение содержит сочетание синтаксиса OpenAPI 2.0 и 3.0, отсюда и ошибки. Должно ли это быть swagger: '2.0' или openapi: 3.0.0 ?

2. Привет, @Helen . Я не знаю разницы между обоими. Я должен задокументировать код в Go. Я хотел бы попробовать go-swagger, но я не могу найти хороший учебник. Итак, я пытаюсь просмотреть разные учебные пособия и адаптировать их к своему коду. Знаете ли вы хорошую ссылку, шаг за шагом?

3. Я изменил некоторую информацию и обновил вопросы, а также выходные данные (ошибки).

Ответ №1:

Чтобы этот код прошел проверку Swagger, мне пришлось:

  • Удалите параметр schema в contractId параметре (метод get);
  • Удалите определение requestBodies и измените schema в contract параметре (метод post);
  • Измените тип contractId в определении Xyz (тип uuid не поддерживается версией 2 Swagger).

Исправленный код приведен ниже:

 swagger: "2.0"
basePath: /myapp/api
info:
  description: My description
  title: My title
  version: 0.1.0
produces:
  - application/json
consumes:
  - application/json
schemes:
  - http
paths:
  /contract:
    get:
      operationId: "Get contract"
      description: Get information
      parameters:
        - in: path
          name: contractId
          description: ID
          required: true
          type: integer
      responses:
        200:
          description: Information...
          schema:
            $ref: "#/definitions/contract"
        404:
          description: "Not found."
    post:
      operationId: "Create"
      parameters:
        - in: body
          name: contractId
          schema:
            $ref: '#/definitions/contract'
      responses:
        200:
          description: Success...
        400:
          description: Problem...
definitions:
  contract:
    title: Contract
    type: object
    properties:
      name:
        title: Name
        type: string
      services:
        title: Services
        type: array
        items:
          title: Service
          $ref: '#/definitions/service'
      xyz:
        title: Xyz
        $ref: '#/definitions/virtualMachine'
  service:
    title: Service
    type: object
    properties:
      containerName:
        title: ContainerName    
        type: string
      ...
      contracts:
        title: Contracts
        type: array
        items:
          title: Contract
          $ref: '#/definitions/contract'    
  xyz:
    title: Xyz 
    type: object
    properties:
      serverId:
        title: ServerID
        type: string
      contractId:
        title: ContractID
        type: string
        format: uuid

Ответ №2:

Может быть, вы можете попробовать отредактировать свой swagger.yml в онлайн-редакторе Swagger.