diff --git a/.gitignore b/.gitignore index b512c09..25c8fdb 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -node_modules \ No newline at end of file +node_modules +package-lock.json \ No newline at end of file diff --git a/README.md b/README.md index 12e566a..f9b4737 100644 --- a/README.md +++ b/README.md @@ -1,112 +1,134 @@ -# Node-RED Swagger Documentation Generator +# Node-RED OpenAPI3 Documentation Generator -This package provides a set of tools for generating Swagger api documentation -based on the HTTP nodes deployed in a flow. +This package provides a set of tools for generating OpenAPI3 documentation based on the HTTP nodes deployed in a flow. + +It is a fork of the https://github.com/node-red/node-red-node-swagger repo with some significant updates of dependencies and restructuring due to the Openapi3-update. ## Usage 1. Install the node module - npm install node-red-node-swagger + npm install node-red-node-openapi - **Note:** until this is published to npm, you will need to install from git: + **Note:** Until this is published to npm, you will need to install from git: - npm install node-red/node-red-node-swagger - -2. Provide a template swagger file in `settings.js`: - - swagger: { - "template": { - "swagger": "2.0", - "info": { - "title": "My Node-RED API", - "version": "0.0.1" + npm install your-username/node-red-node-openapi + +2. Provide a template OpenAPI file in `settings.js`: + + openapi: { + template: { + openapi: "3.0.0", + info: { + title: "My Node-RED API", + version: "0.0.1", + description: "API documentation generated by Node-RED" + }, + servers: [ + { + url: "http://localhost:1880/", + description: "Local server" + } + ], + paths: {}, + components: { + schemas: {}, + responses: {}, + parameters: {}, + securitySchemes: {} + // Add other components here } } } -3. This template will remain unchanged and serve as the basis for the swagger doc. +3. This template will remain unchanged and serve as the basis for the OpenAPI documentation. - **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" - } + **Note:** You may additionally add components like `schemas`, `responses`, `parameters`, `securitySchemes`, etc., to the OpenAPI file in `settings.js` to have those components available for reuse in the generated OpenAPI documentation. + + openapi: { + template: { + // ... (rest of your OpenAPI template) }, - "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." + components: { + schemas: { + MySchema: { + type: "object", + properties: { + name: { + type: "string" + } + } + } + }, + securitySchemes: { + ApiKeyAuth: { + type: "apiKey", + in: "header", + name: "X-API-Key" + } } - ] + // Add other reusable components here + } } -4. 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. - -5. The generated swagger is then available at . +4. After installing the package, you have the option to identify metadata for each HTTP-In node that will be used in the OpenAPI doc generation. + +5. The generated OpenAPI documentation is then available at . -## Path Swagger Generation +## Path OpenAPI Generation -Via the editor, you can define metadata for each particular HTTP-In node to be used in swagger generation. +Via the editor, you can define metadata for each particular HTTP-In node to be used in OpenAPI generation. -To do so, +To do so: 1. Select an HTTP-In node in the editor. -![](readme_images/Capture_00.PNG?raw=true) +![HTTP-In Node](readme_images/Capture_00.PNG?raw=true) -2. 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. -![](readme_images/Capture_01.PNG?raw=true) +2. From the config panel, you can select a user-defined OpenAPI doc from the dropdown. You may create a new metadata definition by selecting "Add new swagger-doc..." and clicking the edit button. +![Config Panel](readme_images/Capture_01.PNG?raw=true) -3. This will launch the swagger config panel, where you have three distinct tabs that make up the swagger documentation. +3. This will launch the OpenAPI config panel, where you have three distinct tabs that make up the OpenAPI documentation. #### Info -![](readme_images/Capture_02.PNG?raw=true) +![Info Tab](readme_images/Capture_02.PNG?raw=true) 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. +* 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](https://help.github.com/articles/github-flavored-markdown) 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 +* 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 -![](readme_images/Capture_03.PNG?raw=true) +![Parameters Tab](readme_images/Capture_03.PNG?raw=true) 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 ): - * _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](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation. +* 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 ). + * _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](https://help.github.com/articles/github-flavored-markdown) 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 -![](readme_images/Capture_04.PNG?raw=true) +![Responses Tab](readme_images/Capture_04.PNG?raw=true) 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](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation. +* 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 response. This could contain examples of use. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) 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. @@ -114,21 +136,16 @@ This tab allows you to define the applicable responses that a user may receive b If no responses are provided, a default response with the reply "success" will be used. -##Swagger-UI - -![](readme_images/Capture_Swagger_UI.PNG?raw=true) - -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. +## Swagger-UI +![Swagger-UI](readme_images/Capture_Swagger_UI.PNG?raw=true) +Swagger-UI is included 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 OpenAPI documentation 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 `/`. +- The `paths` entry of the OpenAPI documentation is generated based on the `HTTP In` nodes present in the flow. +- If an OpenAPI 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](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) \ No newline at end of file +###### Attribute definitions provided come from the [OpenAPI Specification Version 3.1.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) diff --git a/package.json b/package.json index 0e0f8e8..555d660 100644 --- a/package.json +++ b/package.json @@ -1,32 +1,38 @@ { - "name": "node-red-node-swagger", - "version": "0.1.9", - "description": "A set of tools for generating Swagger API documentation based on the HTTP nodes deployed in a flow", + "name": "@digital-tvilling/node-red-openapi-generator", + "version": "0.0.2", + "description": "A set of tools for generating OpenAPI3/Swagger documentation based on the HTTP nodes deployed in a flow. An updated version of the Node-RED Swagger Documentation Generator to support OpenAPI3.", "license": "Apache", "repository": { "type": "git", - "url": "https://github.com/node-red/node-red-node-swagger.git" + "url": "https://github.com/digital-tvilling/node-red-openapi-generator.git" }, "keywords": [ "node-red", - "swagger" + "swagger", + "open-api" ], "node-red": { - "version": ">=0.11.0", + "version": ">=3.0.0", "nodes": { "swagger": "swagger/swagger.js" } }, + "conflicts": { + "node-red-node-swagger": "<0.3.0" + }, "contributors": [ "Nick O'Leary ", "Cody Walker ", - "Jon Silver " + "Jon Silver ", + "Filip Åsblom " ], "dependencies": { - "swagger-ui": "2.1.4", - "i18next-client": "1.11.4" + "i18next": "^23.7.20", + "swagger-ui": "^5.11.1", + "swagger-ui-dist": "^5.11.1" }, "devDependencies": { - "eslint": "^6.4.0" + "eslint": "^8.56.0" } } diff --git a/swagger/swagger-ui/swagger-ui.html b/swagger/swagger-ui/swagger-ui.html index ddb91e5..1f10733 100644 --- a/swagger/swagger-ui/swagger-ui.html +++ b/swagger/swagger-ui/swagger-ui.html @@ -1,147 +1,33 @@ + Swagger UI - - - - - - - - - - - - - - - - - - - - - - - + - -
-

- - -

-

swagger.helpBox.title

-

swagger.helpBox.swaggerIntro

-

swagger.helpBox.swaggerInfo

-

swagger.helpBox.swaggerInstructions0

-

swagger.helpBox.swaggerInstructions1

-

swagger.helpBox.swaggerInstructions2

-

swagger.helpBox.swaggerOutro

-

-
- + +
+ + + + diff --git a/swagger/swagger.html b/swagger/swagger.html index 1b2e1dd..e9813a4 100644 --- a/swagger/swagger.html +++ b/swagger/swagger.html @@ -39,19 +39,11 @@ -
- - -
-
- - -
-
+
    @@ -94,12 +86,6 @@ tags: { value: "" }, - consumes: { - value: "" - }, - produces: { - value: "" - }, parameters: { value: [] }, @@ -125,6 +111,7 @@ swaggerUi.load(); } }); + swaggerDocUrl = window.location.protocol + "//" + window.location.hostname + ":" + window.location.port + RED.settings.httpNodeRoot + 'http-api/swagger.json'; var swaggerFrame = $("