Swagger 2.0 ref spec

Question

I'm having a challenge trying to format this OpenApI(Swagger) Json file. When I try to validate with https://editor.swagger.io/, I get the error.

$ref values must be RFC3986-compliant percent-encoded URIs

When I change the schema's $ref attribute in the file from $ref: '#/definitions/GetResponse[List[CurrencyModel]]' to $ref: '%/definitions/GetResponse[List[CurrencyModel]]'

The errors go away but then the request and response all doesn't show the correct model and instead shows string instead. See screenshots below. First image is with # and second image is with %

swagger: '2.0'
info:
  version: v1
  title: API
  contact:
    name: DEMO
paths:
  /api/Currency/GetCurrencies:
    get:
      tags:
        - Currency
      summary: Get List of Currencies
      description: ''
      operationId: GetAllCurrencies
      consumes: []
      produces:
        - text/plain
        - application/json
        - text/json
      parameters: []
      responses:
        '200':
          description: Returns list of Currencies
          schema:
            $ref: '#/definitions/GetResponse[List[CurrencyModel]]'
        '400':
          description: If an error occur
          schema:
            $ref: '#/definitions/GetResponse[ProducesResponseStub]'
        '404':
          description: If the list of Currencies is null
          schema:
            $ref: '#/definitions/GetResponse[ProducesResponseStub]'
definitions:
  GetResponse[List[CurrencyModel]]:
    type: object
    properties:
      status:
        type: boolean
      data:
        uniqueItems: false
        type: array
        items:
          $ref: '#/definitions/CurrencyModel'
      message:
        type: string
  CurrencyModel:
    type: object
    properties:
      id:
        format: int32
        type: integer
      name:
        type: string
      code:
        type: string
      currencyUTF32Code:
        format: int32
        type: integer
      currencySymbol:
        type: string
        readOnly: true
securityDefinitions:
  Bearer:
    name: Authorization
    in: header
    type: apiKey
    description: Please insert JWT with Bearer into field
security:
  - Bearer: []

user4st · Answer

There are two issues:

Your API definition is missing the GetResponse[ProducesResponseStub] and GetResponse[ProducesResponseStub] schemas which are used in some $refs. You need to either add the missing schemas, or remove the corresponding $refs.
If some schema names contain special characters, they must be URL-encoded in the $ref paths. Replace [ with %5B and ] with %5D, e.g.:
```
# Incorrect
$ref: '#/definitions/GetResponse[List[CurrencyModel]]'

# Correct
$ref: '#/definitions/GetResponse%5BList%5BCurrencyModel%5D%5D'
```
Or better yet, don't use special characters in schema names.

Swagger 2.0 ref spec

1 Answers