carlansley / swagger2 Goto Github PK

I see something like https://github.com/epoberezkin/ajv , they follow the specification, and can handle complex date type like date, which current swagger2 can't.

when using a Parameter Object directly within an Path Object the compiler will error out.

See http://swagger.io/specification/#pathsObject for the definiton.

this snippet causes the error:

... 
paths: 
  /item/{sku}:
    parameters:
      - name: sku
        in: path
        required: true
        description: sku of the `InventoryItem` to lookup
        type: string
    get:
      summary: Get an item by sku
      description: |
        Returns a signle item identified by sku

      responses:
        200:
          $ref: "#/responses/InventoryItemResponse"
        404:
          $ref: "#/responses/UnknownSkuError"

can provide a whole definition if needed.

not sure whats the right way to fix it.
--edit
ok i get why the compile fails, parametersis of type array while the code expects only objects inside the path object.
which is good - because the other way around this bug would go by unnoticed.

/report_download:
get:
description: Report download
operationId: report_download
produces:
- application/zip
parameters:
- name: report_id
in: query
description: report_id is a alphanumeric string to identify the unique report.
required: true
type: string
tags:
- API
responses:
'200':
description: report download
schema:
type: file

note:- I am able to download zip if i have called the same api from browser

Either I am missing something obvious or the request validation method needs to also have the actual path passed in so that it can be validated.

ie:

function request(compiledPath: CompiledPath | undefined,
                        path: string,
                        method: string,
                        query?: any,
                        body?: any,
                        headers?: any): ValidationError[] | undefined

Or make use of the parsing already doen by the like koa, express and others and just ask for a parameters object, ie:

function request(compiledPath: CompiledPath | undefined,
                        pathParameters: { [name: string]: any },
                        method: string,
                        query?: any,
                        body?: any,
                        headers?: any): ValidationError[] | undefined

And then this:

case 'path':
        const actual = compiledPath.name.match(/[^\/]+/g);
        const valueIndex = compiledPath.expected.indexOf('{' + parameter.name + '}');
        value = actual ? actual[valueIndex] : undefined;
        break;

becomes something like:

case 'path':
        value = (pathParameters || {})[parameter.name];
        break;

I have basically just hacked my local javascript inside node_modules and now path parameters are begin validated correctly in my Koa app.

When using file as a parameter like:

  /**
   * @swagger
   * /pakcage:
   *    post:
   *      summary: Upload package
   *      operationId: "upload"
   *      tags:
   *        - Bundles
   *      parameters:
   *        - name: file
   *          in: formData
   *          description: the package
   *          required: true
   *          type: file
   *      consumes:
   *        - "multipart/form-data"
   *      produces:
   *        - "application/json"
   *      responses:
   *        200:
   *          description: the newly created package
   *          schema:
   *            $ref: "#/definitions/Package"
   *        500:
   * /

I receive the following message: Unknown type: file. Looking at the is-my-json-valid plugin it doesn't support this type so thus the failure.

In validate.ts / request(), only resolvedParameters are used. I'm using requestBody which is ignored:

Here's the definition:

post:
  summary: Create a project
  tags:
    - projects
  requestBody:
    description: The Project
    required: true
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Project"

Here's the operation object:

{
  "summary": "Create a project",
  "tags": [
    "projects"
  ],
  "requestBody": {
    "description": "The Project",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "required": [
            "title"
          ],
          "properties": {
            "projectId": {
              "type": "integer",
              "format": "int64",
              "readOnly": true
            },
            "title": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The created project",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "title"
            ],
            "properties": {
              "projectId": {
                "type": "integer",
                "format": "int64",
                "readOnly": true
              },
              "title": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "default": {
      "description": "unexpected error",
      "content": {
        "application/json": {
          "schema": {
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "format": "int32"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "resolvedParameters": []
}

add swagger.loadDocument to load documents async

Schema validator is currently created at the module level, which is adding significant time when importing swagger2. Potentially unnecessarily, if its never used.

I would like to include templated strings for the server, but this doesn't appear to be supported with loadDocumentSync.

Am I missing something, or would it need to be added as a feature?

We don't because json-schema-deref-sync doesn't:
cvent/json-schema-deref-sync#10

Likely need to move to another library.

The current version does not allow setting/getting response headers. Please add support for the same via Koa set and get functions.

It's been a while.

Neither Local or Remote references are resolved when doing a compile, resulting in the swagger ui to display errors about missing definitions.

e.g.

definitions:
  InventoryItem:
    $ref: "InventoryItem.yml"

will not work, neither will

definitions:
  InventoryItem:
    $ref: "file:InventoryItem.yml"

nor

definitions:
  InventoryItem:
    $ref: "./InventoryItem.yml"

i would like to implement this functionality with the consequence that compile will need to be async then. the least problematic way would be to inline the definitions and switching to the async version of deref (it has more features and seems to be a better fit anyway) [http://bojand.github.io/json-schema-deref].

the resolution of external refs should be optional, either as flag or via a sperate function.
(seen something similar here: https://github.com/BigstickCarpet/swagger-parser/blob/master/docs/swagger-parser.md#dereferenceapi-options-callback)

do you have any issues with doing so?
i think loadDocument could be converted to async while doing so also.

I'm having the following parameter specified in my Swagger spec:

name: X-Test-Version
in: header
type: string
required: true
default: 1
When I'm validating the request it returns:
{
"code": "SWAGGER_REQUEST_VALIDATION_FAILED",
"errors": [
{
"expected": {
"type": "string"
},
"where": "header"
}
]
}
Printing out some statements in validate.ts gives me:
for headers:
{......
'x-test-version': '1'
....}
for headers[parameter.name]:
X-Test-Version

Code of validate.ts:
case 'header':
value = (headers || {})[parameter.name];
break;

So it is trying to get the value via headers[X-Test-Version], which cannot be found, so value is undefined.
The following would solve the issue:
case 'header':
value = (headers || {})[(parameter.name).toLowerCase()];
break;

I would like to remove the below error from the Swagger UI by disabling the validation.

{"schemaValidationMessages":[{"level":"error","message":"Can't read from file http://foobar.net/api-docs"}]}

I can find it supports loadDocumentSync, which accepts filepath as input . what about adding support for string in case the doc is aleady in the memory?

e.g.
for yamljs it has YAML.parse ans YAML.load
for yaml it has YAML.parse only but you can read file first, thus we still can deal with both file & string.

The currently version uses yamljs and only implements YAML.load, I can load from file, but cannot do it the other way.

Per spec:

A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the Swagger Object's parameters. There can be one "body" parameter at most.