node-red / node-red-node-swagger Goto Github PK

A set of tools for generating Swagger api documentation based on the HTTP nodes deployed in a flow

License: Apache License 2.0

HTML 91.18% JavaScript 8.82%

node-red-node-swagger's Introduction

Node-RED Swagger Documentation Generator

This package provides a set of tools for generating Swagger api documentation based on the HTTP nodes deployed in a flow.

Usage

Install the node module
```
 npm install node-red-node-swagger
```

Note: until this is published to npm, you will need to install from git:

    npm install node-red/node-red-node-swagger

Provide a template swagger file in settings.js:

 swagger: {
   "template": {
     "swagger": "2.0",
     "info": {
       "title": "My Node-RED API",
       "version": "0.0.1"
     }
   }
 }

This template will remain unchanged and serve as the basis for the swagger doc.

Note: You may additionally add parameters to the swagger file in 'settings.js' to have those parameters automatically added to each path in the generated swagger doc.

    "swagger": {
      "template": {
        "swagger": "2.0",
        "info": {
          "title": "My Node-RED API",
          "version": "0.0.1"
        }
      },
      "parameters": [
        {
          "name": "parameterA",
          "type": "string",
          "in": "header",
          "required": false,
          "description": "This is a test parameter to show how parameters are automatically added to each path in the generated swagger doc."
        }
      ]
    }

After installing the package, you have the option to identify metadata for each HTTP-In node that will be used in the swagger doc generation.
The generated swagger is then available at http://localhost:1880/http-api/swagger.json.

Path Swagger Generation

Via the editor, you can define metadata for each particular HTTP-In node to be used in swagger generation.

To do so,

Select an HTTP-In node in the editor.
From the config panel, you can select a user-defined swagger doc from the dropdown. You may create a new metadata definition by selecting "Add new swagger-doc..." and clicking the edit button.
This will launch the swagger config panel, where you have three distinct tabs that make up the swagger documentation.

Info

This tab allows you to provide the basic information about the attached paths.

Summary - A short summary of what the operation does. For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
Description - A verbose explanation of the operation behavior. GFM syntax can be used for rich text representation.
Tags - A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. These should be provided as a comma-separated list.
Consumes - A list of MIME types the operation can consume. These should be provided as a comma-separated list
Produces - A list of MIME types the operation can produce. These should be provided as a comma-separated list.
Deprecated - Declares this operation to be deprecated. Usage of the declared operation should be refrained.

Parameters

This tab allows you to configure the parameters that can be used with the particular operation.

Name - The name of the parameter. Parameter names are case sensitive.
In - The location of the parameter. There are four supported locations of the parameter
- Query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
- Header - Custom headers that are expected as part of the request.
- Form - Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded or multipart/form-data are used as the content type of the request. This is the only parameter type that can be used to send files, thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
- Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.
Description - A brief description of the parameter. This could contain examples of use. GFM syntax can be used for rich text representation.
Required - Determines whether this parameter is mandatory.
Type - The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object).
Format - The extending format for the previously mentioned type.

If a body parameter is selected, the user will provide properties included in the body object, rather than specifying a type.

Responses

This tab allows you to define the applicable responses that a user may receive back from the operation.

Code - You can either select to define the default response, or to provide a specific HTTP status code that the response will be applicable for. A default response is used to cover other undeclared responses
Description - A short description of the parameter. This could contain examples of use. GFM syntax can be used for rich text representation.
Properties - The properties are the components that build up the schema of the response.
Name - The key name for the particular property.
Type - The type of the property.
Format - The extending format for the previously mentioned type.

If no responses are provided, a default response with the reply "success" will be used.

##Swagger-UI

Swagger-UI is including in the plugin. Once loaded, the plugin will show a swagger tab in the node-red sidebar. From here, you can see the dynamically generated swagger for the current flow. Additionally, you can use the test function to try out your API directly from the editor, providing any parameters you have defined in the docs for the HTTP-In nodes. The Swagger-UI will automatically refresh any time the flow is redeployed.

Notes

the paths entry of the swagger is generated based on the HTTP In nodes present in the flow.
if a swagger template is not provided, the example above is used as the default.
if basePath is not set in the template, it is set to the value of httpNodeRoot if that value is something other than /.

Attribute definitions provided come from the Swagger 2.0 Spec

node-red-node-swagger's People

Contributors

Stargazers

Watchers

node-red-node-swagger's Issues

Settings through node?

I have multiple flows and multiple json files. I would like to get basePath, info from the flow itself.
Is this possible? I do not want to edit swagger.json or settings.js each time.

Swagger UI not displayed

When loading Node-red UI in chrome, following exception is printed in browser console:

Uncaught TypeError: Cannot read property 'type' of undefined
at Object. (swagger-ui.js:254)
at Object.10 (swagger-ui.js:778)
at Object.f [as inverse] (handlebars-2.0.0.js:27)
at Object. (handlebars-2.0.0.js:27)
at Object.9 (swagger-ui.js:773)
at Object.f [as inverse] (handlebars-2.0.0.js:27)
at Object. (handlebars-2.0.0.js:27)
at Object.main (swagger-ui.js:789)
at e (handlebars-2.0.0.js:27)
at s.render (swagger-ui.js:26072)

Responses.description is a required field

Per Swagger 2.0 Spec, Responses are required.
Every response object is required to have a description.
The placeholder currently does not have one
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responseObject

"responses":{"default":{}},

Don't produce swagger for http-in nodes without a corresponding http-out node

Scenario -

1) add HTTP In (say /path1) to canvas
2) add a function node but never add an HTTP Out node
3) in swagger ui, you'll see we generate swagger for the /path1 resource, but if you test it, it'll never return

Need to add a check to only include http-in nodes if they have an http-out node as well.

Inline schema for parameters missing type property

Swagger UI from Swagger.io recently added the support for the inline schema.

Here is the issue:
swagger-api/swagger-ui#1133

and here is the commit that fixed it:
swagger-api/swagger-js@91eff39

I have noticed that the inline schema swagger node generates is missing type property for schema object.

The following inline schema displays "undefined" under Data Type column of Swagger UI's parameter view.

"parameters": [
{
  "name": "body",
  "in": "body",
  "required": false,
  "schema": {
    "properties": {
      "message": {
        "type": "string"
      }
    }
  }
}
]

The following inline schema displays the model correctly under Data Type column.

"parameters": [
{
  "name": "body",
  "in": "body",
  "required": false,
  "schema": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string"
      }
    }
  }
}
]

Based on the fact that the first example works fine in Swagger Editor (http://editor.swagger.io/) but not in Swagger UI, I am a little puzzled whether this type property should be there by the spec though.

Parameters not generating correctly in swagger doc

It seems that the parameters code is never actually getting called. The generateTypeRow function is not actually setting the class and style on the generated div. Therefore the code that is parsing the type rows never finds the child with the .node-swagger-type-row class. Additionally, parameters (or properties in a body param) are not correctly attaching the items attribute to array types.

Error

D:\Train\Priyanka\PriyankaDemo>npm install
npm WARN saveError ENOENT: no such file or directory, open 'D:\Train\Priyanka\PriyankaDemo\package.json'
npm WARN enoent ENOENT: no such file or directory, open 'D:\Train\Priyanka\PriyankaDemo\package.json'
npm WARN PriyankaDemo No description
npm WARN PriyankaDemo No repository field.
npm WARN PriyankaDemo No README data
npm WARN PriyankaDemo No license field.

up to date in 0.065s

please help cant understand what to do
in install node js latest version:
C:\Users\Priyanka>node -v
v9.3.0
C:\Users\Priyanka>npm -v
5.5.1

no way to set `operationId` to the operation object

see here
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object

It is not mandatory but It actually required if you want to deploy on GCP see here
https://cloud.google.com/endpoints/docs/openapi/configure-endpoints#operationid

As a solution please just add a field for to set a value.
The uniqueness can be left to the user to take care of.

Thanks.

Swagger UI becomes empty when an endpoint has a param and a query

Hi!

Before I add the query parameter:

After I add the query parameter (and deploy):

Notice that the SwaggerUI doesn't display the endpoints anymore

Swagger Doc Generation failing in Sub Flows

When HTTP In and HTTP Response nodes are included in a "sub flow", Swagger doc generation is failing with the following error in the log at line 132 in swagger.js.

TypeError: Cannot read property 'type' of null
at checkWiresForHttpResponse (/home/mphil/nodered/node_modules/node-red-node-swagger/swagger/swagger.js:132:23)
at /home/mphil/nodered/node_modules/node-red-node-swagger/swagger/swagger.js:52:20

I am testing with Node-RED version 0.14.5 and node-red-node-swagger version 0.1.8.

The end point itself is working fine if I invoke it directly and only swagger doc generation seems to be an issue. Please let me know if you need any additional details.

No host and schemes fields in swagger

What are the steps to reproduce?

Install node-red-node-swagger on Node-RED flow editor.
Create REST API using http-in, template, http response nodes.
Import the generated swagger definition on Swagger Editor using the URL, http://localhost:1880/http-api/swagger.json .
Access the endpoint from the Swagger Editor.

What happens?

"404 Not Found" error occurred because the Swagger Editor access the own URL, https://editor.swagger.io/

What do you expect to happen?

The swagger definition contains host and schemes fields. And the Swagger Editor can access the endpoint on Node-RED.

Please tell us about your environment:

Node-RED version: 1.2.9
Node.js version: 10.20.1
npm version: 7.6.0
Platform/OS: macOS Big Sur 11.2.3
Browser: Google Chrome 89.0.4389.114 (Official Build) (x86_64)

Using parameters from the path

Hi First of all I would like to compliment you with the swagger plugin, great tool simple to use and worked in one go.

On thing I did not see... (maybe something that could be added?)

When I have a url like this: /pet/{petId}/name which allows me to modify the name of a pet based on its id then I would normally specify this like so:

"parameters":[
{
"name":"petId",
"in":"path",
"description":"ID of pet to return",
"required":true,
"type":"integer",
"format":"int64"
}

When I look in the node-red editor the options for parameter are:
*query
*header
*formdata
*body

Any way you could add to that the "path" ?

Swagger not working in latest version

Just after i updated node-red to updated version, it is giving this error on my multiple instances.

Blank space below the Swagger-UI tab

When we switched to using "deploy" events, we removed the banner explaining the need for manual refresh to the user. However, we did not remove the additional space from the calculation in the onResize handler.

"List Operations" in sidebar does not include flows with embedded link out/in pairs

I tracked down why my new http endpoint was not showing in the Swagger sidebar... the code searches from the http in node until it finds a connected http response node -- and if it doesn't find one, it won't show in the Operation List.

This check is good -- however, in my case, the http response node IS connected, but through a link out/in pair, which is causing my api to be excluded from the Operations list. The function that does this validation is:

    function checkWiresForHttpResponse (node) {
        var wires = node.wires[0];
        for(var i in wires){
            var newNode = RED.nodes.getNode(wires[i]);
            if(newNode.type == "http response"){
                return true;
            } else if(checkWiresForHttpResponse(newNode)){
                return true;
            }
        }
        return false;
    }

I tried to "hop over" the link nodes, by checking if node.type === "link out", then use the node.links array (instead of wires[0]). Although node.links exists in the flows.json file, once it is loaded into the runtime, that attribute is no longer available... (?) hmmm

So it probably requires an intermediate node lookup, something like this (untested)?

            var newNode = RED.nodes.getNode(wires[i]);
            if (newNode.type == "link out") {
                newNode = RED.nodes.getNode(node.links[0]);
            }

However, this assumes there is only one link in connected to each link out -- so some iteration will probably be needed. And will this work for wires connected to subflows? Probably not, which makes me wonder if this validation is even necessary.

Today, any http in node wired to an http response node will appear in the list of Swagger Operations. Instead, I suggest we eliminate the checkWires validation, and only include those http in nodes that have a swagger-doc node defined. I'd be happy to submit a PR with these and any other necessary changes, if you agree with my assessment.

Cannot use status on node object when using RED.nodes.eachNode(function(node))

RED.nodes.eachNode(function(node) {
    ...
    node.status({});
    ...
});

results in

TypeError: Object #<Object> has no method 'status' at C:\Users\cody\Downloads\node-red-0.12.0\node-red-0.12.0\node_modules\node-red-node-swagger\swagger\swagger.js:126:26

Need to NLS content in help block from Swagger tab

We won't be able to use the same mechanics to NLS the rest of the nodeRED editor.

No Tags/Releases created for node-red-node-swagger releases

Nick, can we get Tags and Releases created in github when we cut releases for node-red-node-swagger? Thanks.

Install fails with ENOENT on package.json

I tried to install this node with "npm install node-red-node-swagger" on my ".node-red" directory. The install of this node fails to complete with the console statements below.

user1@development:~/.node-red$ npm install node-red-node-swagger
/home/user1/.node-red
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
└── [email protected]
npm WARN enoent ENOENT: no such file or directory, open '/home/user1/.node-red/package.json'
npm WARN .node-red No description
npm WARN .node-red No repository field.
npm WARN .node-red No README data
npm WARN .node-red No license field.

Here are the versions that I am running:
npm : 3.9.6
node : 5.10.1
node-red : 0.13.4

I am trying this on Amazon Linux in AWS (Linux development 3.2.0-4-amd64)

Kindly help.

Maximum call stack size exceeded

Unable to load swagger.json or swagger tab when running local or in Bluemix environment. Getting the following:


16 Aug 09:05:41 - [info] Node-RED version: v0.19.1
16 Aug 09:05:41 - [info] Node.js  version: v8.9.0
16 Aug 09:05:41 - [info] Linux 4.15.0-30-generic x64 LE
16 Aug 09:05:41 - [info] Loading palette nodes
16 Aug 09:05:41 - [warn] rpi-gpio : Raspberry Pi specific node set inactive
16 Aug 09:05:41 - [warn] rpi-gpio : Cannot find Pi RPi.GPIO python library
16 Aug 09:05:42 - [info] Settings file  : /home/ibm/.node-red/settings.js
16 Aug 09:05:42 - [info] Context store  : 'default' [module=memory]
16 Aug 09:05:42 - [info] User directory : /home/ibm/.node-red
16 Aug 09:05:42 - [warn] No active project : using default flows file
16 Aug 09:05:42 - [info] Flows file     : /home/ibm/.node-red/flows_ubuntu.json
16 Aug 09:05:42 - [info] Server now running at https://127.0.0.1:1880/
16 Aug 09:05:42 - [debug] loaded flow revision: e2853381858f25f5a9e16fda79676174
16 Aug 09:05:42 - [debug] red/runtime/nodes/credentials.load : no user key present
16 Aug 09:05:42 - [debug] red/runtime/nodes/credentials.load : using default key
16 Aug 09:05:42 - [debug] red/runtime/nodes/credentials.load : keyType=system
16 Aug 09:05:42 - [warn] 

---------------------------------------------------------------------
Your flow credentials file is encrypted using a system-generated key.

If the system-generated key is lost for any reason, your credentials
file will not be recoverable, you will have to delete it and re-enter
your credentials.

You should set your own key using the 'credentialSecret' option in
your settings file. Node-RED will then re-encrypt your credentials
file using your chosen key the next time you deploy a change.
---------------------------------------------------------------------

16 Aug 09:05:42 - [trace] runtime event: {"id":"runtime-state","retain":true}
16 Aug 09:05:42 - [trace] runtime event: {"id":"runtime-deploy","payload":{"revision":"e2853381858f25f5a9e16fda79676174"},"retain":true}
16 Aug 09:05:42 - [info] Starting flows
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : global
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : a21d4ae5.cb9438
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : b262e1c0.ed831
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : 4e535d22.05cdb4
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : 6f341112.bd52
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : 34d91e5c.183102
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : f5a9c075.9f5d8
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : 1abb4e90.084d21
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : 5318b31f.b1989c
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : bd9ef457.5a1df8
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : d71650aa.72d48
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : b5822f42.92467
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : 6842fcef.90a604
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : c0344331.0f921
16 Aug 09:05:42 - [debug] red/nodes/flows.start : starting flow : 55bc520f.e6b38c
16 Aug 09:05:42 - [trace] runtime event: {"id":"runtime-state","retain":true}
16 Aug 09:05:42 - [info] Started flows
RangeError: Maximum call stack size exceeded
    at Object.getNode (/home/ibm/.nvm/versions/node/v8.9.0/lib/node_modules/node-red/red/runtime/nodes/flows/index.js:177:17)
    at checkWiresForHttpResponse (/home/ibm/.node-red/node_modules/node-red-node-swagger/swagger/swagger.js:131:37)
    at checkWiresForHttpResponse (/home/ibm/.node-red/node_modules/node-red-node-swagger/swagger/swagger.js:134:23)
    at checkWiresForHttpResponse (/home/ibm/.node-red/node_modules/node-red-node-swagger/swagger/swagger.js:134:23)
    at checkWiresForHttpResponse (/home/ibm/.node-red/node_modules/node-red-node-swagger/swagger/swagger.js:134:23)

Doesn't seem to work with named parameters (ie /user/:name)

When adding an endpoint with a parameter, something like /user/:name it doesn't seem to be picked up by the doc.

Omit otherwise empty fields

At the bottom of this issues is a flow that creates a tiny subset of the standard pet store example.

Looking at the generated swagger, we are getting a lot of empty schema/properties entries. We should omit these if they are empty (as they are not required by the spec)

"responses": {
      "405": {
        "description": "Invalid Input",
        "schema": {
          "properties": {}
        }
      }
    }

[{"id":"6e85ee6e.917a1","type":"swagger-doc","summary":"Returns a single pet","description":"","tags":"","consumes":"","produces":"application/xml,application/json","parameters":[{"name":"petId","in":"header","description":"ID of pet to return","required":true,"type":"string","format":"long"}],"responses":{"200":{"schema":{"properties":{}},"code":"200"},"400":{"description":"Invalid ID supplied","schema":{"properties":{}},"code":"400"},"404":{"description":"Pet not found","schema":{"properties":{}},"code":"404"}},"deprecated":true},{"id":"ac5b4676.53a4b8","type":"swagger-doc","summary":"Add a new pet to the store","description":"","tags":"","consumes":"","produces":"","parameters":[{"name":"body","in":"body","description":"Pet object that needs to be added to the store","required":true,"schema":{"properties":{}}}],"responses":{"405":{"description":"Invalid Input","schema":{"properties":{}},"code":"405"}},"deprecated":true},{"id":"ea6bcf4e.15943","type":"http in","name":"","url":"/pet","method":"post","swaggerDoc":"ac5b4676.53a4b8","x":599,"y":413,"z":"396c2376.c693dc","wires":[[]]},{"id":"ccd7bb57.332848","type":"http in","name":"","url":"/pet/:petId","method":"get","swaggerDoc":"6e85ee6e.917a1","x":602,"y":353,"z":"396c2376.c693dc","wires":[[]]}]

npm publish request

I added Japanese translations in the pull request, #76 . I appreciate it if the latest module is published on the npmjs repository because my colleagues are writing a document in Japanese language using this module currently.

Swagger contrib doesn't load

I have installed it and it trieds to load it in node-red

I receive the following message ( also after creating the settings.js file)

Failed to load 'node-red-contrib-swagger/swagger'
SyntaxError: Unexpected token <

How can you configure enum parameters in the query?

In the Swagger-YAML you can configure call parameters as ENUM (selection list). How can this be transferred to the parameterization in the NODE-RED Swagger documentation?

As an example in YAML

  /pet/findByStatus:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by status"
      description: "Multiple status values can be provided with comma separated strings"
      operationId: "findPetsByStatus"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - name: "status"
        in: "query"
        description: "Status values that need to be considered for filter"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "available"
          - "pending"
          - "sold"
          default: "available"

In NODE-RED there is no selection for ENUM or default settings, right?

Unclear instructions for step 2

I'm quite new to node-red and swagger and I was trying to follow along to the instructions for installation and I'm not too sure what is meant by:

Provide a template swagger file in settings.js:

swagger: {
  "template": {
    "swagger": "2.0",
    "info": {
      "title": "My Node-RED API",
      "version": "0.0.1"
    }
  }
}

I've tried pasting this in various places in ~/.node-red/settings.js and I'm getting syntax errors when trying to start node-red.
e.g.

/home/ubuntu/.node-red/settings.js:22
  "template": {
            ^
Error loading settings file: /home/ubuntu/.node-red/settings.js
[SyntaxError: Unexpected token :]

This is probably quite a silly question but I googled around and couldn't find much info.

HTTP-In affinity to swagger-doc node

The HTTP In edit dialog currently displays the default, automatically generated, config node select box if the swagger node is installed.

Unlike other uses of config nodes, I don't think it makes sense to allow the user to pick from a list of existing swagger-doc nodes. There should be a closer affinity between the nodes - it either has a swagger-doc node associated or it doesn't.

We could either hack in special handling for this case in the HTTP In node, or add a more generic solution in the editor. Where a node identifies its relationship to a config node, we could add a flag (name tbd) to indicate the UI should offer a single button (either 'add' or 'edit' depending on what state it is in) rather than the select box.

Swagger node status not showing nls value

Instead of pulling the value from the locale document, the swagger status is showing "swagger.status.missingconfig".

I believe the swagger locale namespace is not being picked up before the editor is being loaded. This timing issue is causing the swagger statuses to be unknown to the editor.

Swagger crash when disabling a flow

typeError: Cannot read property 'type' of null
at checkWiresForHttpResponse (/data/node_modules/node-red-node-swagger/swagger/swagger.js:132:23)
at /data/node_modules/node-red-node-swagger/swagger/swagger.js:52:20
at Object.eachNode (/usr/src/node-red/node_modules/node-red/red/runtime/nodes/flows/index.js:168:13)
at /data/node_modules/node-red-node-swagger/swagger/swagger.js:50:19
at Layer.handle [as handle_request] (/usr/src/node-red/node_modules/express/lib/router/layer.js:95:5)
at next (/usr/src/node-red/node_modules/express/lib/router/route.js:137:13)
at Route.dispatch (/usr/src/node-red/node_modules/express/lib/router/route.js:112:3)
at Layer.handle [as handle_request] (/usr/src/node-red/node_modules/express/lib/router/layer.js:95:5)
at /usr/src/node-red/node_modules/express/lib/router/index.js:281:22
at Function.process_params (/usr/src/node-red/node_modules/express/lib/router/index.js:335:12)

Feature Request: possibility "hide" http-in nodes in swagger

Hy Nick,

some of my http-in nodes (or better rest api) provide "internal" functions, that should not be in de swagger doc. The possibility to "hide" a specific node in the swagger doc would be nice.

greetings from Heidelberg - Michael

Path parameters not supported

An HTTP In node can identify named path parameters using the Express syntax:

/pet/:petId

The swagger doc node should spot those parameters and automatically add parameter entries for them.

In the generated swagger, the format needs to be transformed to:

/pet/{petId}

Swagger node doesn't support multiple outputs nodes

I have created flow with multiple outputs function node:

The swagger output doesn't contains this path, since the response node is connected to the second output.

When I have connected it to the first output - it worked.

I think the following line is problematic:
var wires = node.wires[0]; ( in function: checkWiresForHttpResponse swagger.js:129)

I changed it to be like that:

  function checkWiresForHttpResponse(node) {
      var outputs = node.wires;
      for (var o in outputs) {
          for (var w in outputs[o]) {
              var newNode = RED.nodes.getNode(outputs[o][w]);
              if (newNode.type == "http response") {
                  return true;
              } else if (checkWiresForHttpResponse(newNode)) {
                  return true;
              }
          }
      }
      return false;
  }

and it solved the problem.

Current status

Just wondering about the current status and future of this node.

Swagger-UI <v3 is deprecated.
The last release was 3 years ago.
There are 5 outstanding PRs.
Some past modifications to the code resulted in the current version giving 500 server errors when flows triggered by http-in nodes become complex. For example, an http post triggers a flow, which quickly and dutifully returns a response; meanwhile the flow triggers other parallel paths which can even be (conditionally) circular/recursive. The node-red-node-swagger code tries to follow all these paths, resulting in the errors and rendering the entire thing useless. In fact I've never managed to get it to populate the UI sidebar when the flows get past simple request-response.

The error in the log trace is:
TypeError: Cannot read property 'type' of null at checkWiresForHttpResponse

Reverting this one change originally discussed in #17 makes some of the badness go away, but the Swagger UI panel still shows "I see you're lacking Swagger doc..." and although List Operations seems to display endpoints, the details (parameters etc) of each endpoint don't show up.

Happy to contribute if I can.

How can I specify the auth options?

Flags for unconfigured swagger doc in http nodes

The following scenario has been brought up.

1) add HTTP In (say /path2) to canvas but don't Add/Edit the Doc settings (aka don't define any response codes)
2) wire in a function node and add an HTTP Out node
3) in swagger ui, you can test the API, but there is no definition of the expected response codes or output

If you have the swagger plugin enabled, and have http endpoints in your flows, but have not defined any additional documentation via the config, we use a placeholder in the swagger doc generation.

Should we present the user with a warning flag on the corresponding nodes, informing the user that they do not have any additional swagger doc attached?

This can be done in the swagger plugin itself, along with the check for http in nodes, that way we aren't changing the logic in the core nodes themselves.

Thoughts, @knolleary ?

Viewing the Swagger-UI outside of the NR editor

Hi!
I would like to share the Swagger UI to colleagues to test the API without being able to modify the flows. So I thought I could browse directly to http://localhost:1880/swagger-ui/swagger-ui.html but it displays an error message
"I see you're lacking Swagger doc..." instead of the populated Swagger UI that is normally displayed as an iframe in the Node-Red editor. Do you think it'd be easy to implement?

/http-api/swagger.json is not CORS enabled

I have swagger UI on other server and I try to link with my node-red swagger API but CORS headers are not found on /http-api/swagger.json

curl -I http://myhost:1880/http-api/swagger.json
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 921
ETag: W/"399-O+kHybLKLLCZ4lh4LITBaw"
Date: Wed, 20 Jan 2016 19:58:17 GMT
Connection: keep-alive

Placing the configuration:

httpNodeCors: {
        origin: "*",
        methods: "GET,PUT,POST,DELETE"
    },

it still happens

Copy/Paste of an http-in node with Swagger docs does not copy the doc files

I tried to duplicate my http-in node (url = /nodes) in order to add a named parameter (url = /nodes/:type). Any changes I made to either list of query parameters would overwrite the changes I made in the other copy of the node. Is this the expected behavior when two nodes share the same root url?

I thought it might be because the root of the path is identical, but even after changing the url of the first node, the two nodes are sharing the same swagger doc file. I ended up having to remove both nodes and recreate them from scratch.

Dynamically generated swagger doc is overwriting endpoint data, even if it is using two separate operations

For instance, GET /test and POST /test results in swagger doc being generated only showing POST /test

If the path does not include a leading '/', swagger does not place one

Node-RED editor handles this by including a leading '/', whether the user includes it or not in the UI. However, when we parse it for swagger generation, it's not included when searching there.

Additional functionality needs to be included to add a leading '/' if there is not one when generating the swagger paths.

Swagger help text does not load initially

If you allow the editor to load completely, and there are no flows that generate swagger doc, the help text does not load initially. If you deploy flows and there are no swagger paths, then the help doc shows in the swagger tab.

Remove CollectionFormat from arrays in Body params

CollectionFormat is not allowed in body params, since JSON already provides a standard for how arrays should be handled. Currently, we have a workaround that just doesn't pass along the CollectionFormat set in the UI. Now that I know there's a reason behind it, we need to remove the CollectionFormat dropdown from the ui for body params.

"popover is not a function" when trying to open SwaggerUI

Since Node-RED 1.0.0, the Swagger UI is not working (http in > Properties > Edit), usually there should be 3 tabs there called “Info”, “Parameters” and “Responses”, but the content of the 3 tabs is displayed in the same one and the button to add parameters and responses is not working, I can see this error in the browser console:

“oneditprepare 24be5a7.3a18ba6 swagger-doc TypeError: $(...).popover is not a function”

Unable to load SwaggerUI in Embedded architecture

We are running NR in Embedded architecture
Swagger UI does not load in NR editor.
The following error is printed to the Browser console:
GET http://localhost:1881/apihttp-api/swagger.json 404 (Not Found) Unable to load SwaggerUI
Please suggest how to solve that
Thanks!

Add capability to walk through 'link' nodes and avoid crash when newNode is null

changing the function in swagger.js by this will add the two capabilities

Unable to load SwaggerUI

Hi , I tried implementing Swagger following your instructions.

I have it installed correctly but my swagger.json throws the following error..

In the developer console I get the log as below:

Node-Red Log:

Node Structure:

.node-red -->
node_module -->

node-red-node-swagger
swagger-ui

Please help fix my problem..

Thank You!

"Deprecated" box getting ticked unexpectedly

Steps to recreate:

add new HTTP In node
edit node, add new swagger-doc node
At this point, Deprecated is not ticked
Close swagger dialog (with 'Ok' not 'Cancel')
Click to edit swagger-doc
Deprecated is now ticked

Need to check if this is happening with any other checkboxes in the swagger node UI.

Try It options not available for POST requests with JSON request body

Hi Nick - this tool has been our biggest find in recent days as node-red becomes an important part of a our mini-api-server gateways.
However, wondering if we're missing something with POST end points that expect JSON request bodies - since the try it UI does not generate any option to provide the JSON (please see below screen shots)?
We are running on:

Node-red 1.0.6 in docker
0.1.9 of node-red-swagger-node

Properties

in Node red, we use swagger,
in the "Docs",
Responses -> Properties -> Type
it is limited to simple types(string, number, integer, boolean, array),
do not it support an object?
Our project need response a object in the json .

do you have some idea about this ?
thanks very much

Path as parameter is needed

Is there any workaround?
In petshop example http://petstore.swagger.io/#!/store/getOrderById this one explains the need:
GET /store/order/{orderId}