Swagger UI 2.1 Застрял «выборка списка ресурсов»

Question

У меня есть API RESTful, который я создал недавно, и я не буду помнить, как его использовать через несколько месяцев. Я решил документировать свой API с помощью Swagger, однако я схожу с ума.

Я использовал http://editor.swagger.io/ для создания файла YAML, который затем конвертирую в файл JSON, который может использовать Swagger. Когда я помещаю файл в пользовательский интерфейс Swagger, он просто застревает в fetching resource list: localhost/swagger.json, а консоль говорит Uncaught TypeError: Cannot read property '$ref' of undefined.

Я использую версию 2.1.0-alpha.5 из Swagger UI.

Вот моя спецификация файл:

 
swagger: '2.0' 
info: 
    title: TITLE 
    description: BLAH, BLAH, BLAH, ETC 
    version: "1.0b" 
host: api.example.com 
schemes: 
- http 
basePath: /v1 
produces: 
- application/json 
paths: 
    /match.json: 
    get: 
    #summary: Match Data 
     description: Used for getting data about a match 
     parameters: 
     - name: id 
      in: query 
      description: The match ID of from a game 
      required: true 
      type: integer 
      format: int32 
     - name: key 
      in: query 
      description: API key used for authentication. 
      required: true 
      type: string 
     responses: 
     200: 
      description: Returns match data 
      schema: 
      type: array 
      items: 
       $ref: '#/definitions/MatchData' 
     default: 
      description: Unexpected error 
      schema: 
      $ref: '#/definitions/Error' 

definitions: 
    MatchData: 
    properties: 
     info: 
     type: integer 
     format: int64 
     description: General information about the match 
     time: 
     type: integer 
     format: int64 
     description: Information about the start/end time 
     stats: 
     type: array 
     format: int64 
     description: Stats about the match 
    Error: 
    required: 
    - errorID 
     - message 
    properties: 
     errorID: 
     type: string 
     description: Error ID. 
     message: 
     type: string 
     description: Information about the error. 

Answer 1

Я проверил вашу спецификацию, и пока я не получаю ту же ошибку, что вы делаете, спецификация действительно недействительна.

Если вы посмотрите на #/definitions/MatchData/properties/stats, вы увидите, что вы определяете type: array, но вы не предоставляете свойство «items» рядом с ним, чтобы сказать, какой массив он (и это обязательно). Возможно, вы намеревались использовать type: integer, как и над ним, что соответствует format: int64.

Поскольку я не знаю, что вы намереваетесь предоставить, сложно дать точное решение, но если вы добавите комментарий к тому, что вы намеревались сделать, я мог бы предоставить более подробный ответ.

После некоторого дополнительного тестирования я обнаружил, что в пользовательском интерфейсе есть ошибка. После того, как вы сделаете эту модификацию и загрузите спецификацию, сама операция не будет расширяться, если вы не нажмете на ссылку Expand Operations. Я открыл об этом issue, не стесняйтесь следить за ним.

Answer 2

Эта проблема может быть вызвана некоторыми ошибками отступа в файле yaml, которые на самом деле не отображались в редакторе Swagger. Проверьте все свои определения и отобразите их в ожидании в предварительном просмотре, который вы можете увидеть в редакторе Swagger (особенно проверьте MatchData).

Вы также можете попытаться дать:

responses: 
200: 
    description: Returns match data 
    schema: 
    type: array 
    items: 
     schema: 
     $ref: '#/definitions/MatchData' 

Answer 3

Для нашего случая мы использовали Swagger-PHP и мы имеем: * @SWG \ Response ( * ответ = 200, * описание = "ответ приложение " * @SWG \ Schema ( * Тип =" массив» *) *),

но мы пропустили "* @SWG \ Items (реф =" #/Определения/домашнее животное ")". После удаления «@SWG \ Schema (», она работает, например,

*  @SWG\Response(
*   response=200, 
*   description="app response" 
* ),