Swagger UI 2.1 Zatrzymany "pobieranie listy zasobów"

Question

Mam RESTful API, które stworzyłem niedawno i nie będę pamiętał, jak go używać w ciągu kilku miesięcy. Zdecydowałem się udokumentować moje API za pomocą Swaggera, ale zwariowałem.

Użyłem http://editor.swagger.io/ do utworzenia pliku YAML, który następnie konwertuję do pliku JSON, którego może używać Swagger. Kiedy umieszczam plik w interfejsie użytkownika Swagger, po prostu utknie w fetching resource list: localhost/swagger.json, a konsola mówi: Uncaught TypeError: Cannot read property '$ref' of undefined.

używam wersji 2.1.0-alpha.5 od Swagger UI.

Oto mój plik spec:

 
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

Przetestowałem swoją specyfikację, a ja nie dostaję ten sam błąd, co robisz, spec rzeczywiście jest nieprawidłowy.

Jeśli spojrzysz na #/definitions/MatchData/properties/stats, zobaczysz, że definiujesz type: array, ale nie podajesz obok niej właściwości "items", aby określić, która to tablica (i jest to obowiązkowe). Być może zamierzałeś użyć type: integer, podobnie jak właściwości nad nim, co jest zgodne z format: int64.

Ponieważ nie wiem, co zamierzałeś podać, trudno jest podać dokładne rozwiązanie, ale jeśli dodasz komentarz z tym, co zamierzasz zrobić, mogę podać bardziej szczegółową odpowiedź.

Po kilku dodatkowych testach odkryłem, że w interfejsie jest błąd. Po wprowadzeniu tej modyfikacji i załadowaniu specyfikacji operacja nie rozwinie się, dopóki nie klikniesz linku Expand Operations. Otworzyłem o tym issue, nie krępuj się śledzić go tam.

Answer 2

Ten problem może wynikać z błędów wcięć w pliku yaml, które w rzeczywistości nie pojawiły się w edytorze Swagger. Sprawdź wszystkie definicje i czy są one wyświetlane zgodnie z oczekiwaniami w podglądzie, które możesz zobaczyć w edytorze Swagger (szczególnie sprawdź MatchData).

Możesz także spróbować podając:

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

Answer 3

Na naszym przypadku użyliśmy Swagger-php i mamy: * @SWG \ odpowiedź ( * Pasmo = 200, * description = "App odpowiedź " * @SWG \ Schema ( * type =" tablica” *) *),

ale brakowało nam "* @SWG \ egzemplarze (ref =" #/definicje/pET ")". Po usunięciu "@SWG \ Schema (", to działa np

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