NIFI-14144 Declare status code and content for success in OpenAPI spec

[EndzeitBegins]

Summary

NIFI-14144

---

swagger.json before change (excerpt)

{
"/access/token" : {
      "post" : {
        "description" : "The token returned is formatted as a JSON Web Token (JWT). The token is base64 encoded and comprised of three parts. The header, the body, and the signature. The expiration of the token is a contained within the body. It is stored in the browser as a cookie, but also returned inthe response body to be stored/used by third party client scripts.",
        "operationId" : "createAccessToken",
        "requestBody" : {
          "content" : {
            "application/x-www-form-urlencoded" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "password" : {
                    "type" : "string"
                  },
                  "username" : {
                    "type" : "string"
                  }
                }
              }
            }
          }
        },
        "responses" : {
          "400" : {
            "description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."
          },
          "403" : {
            "description" : "Client is not authorized to make this request."
          },
          "409" : {
            "description" : "The request was valid but NiFi was not in the appropriate state to process it."
          },
          "500" : {
            "description" : "Unable to create access token because an unexpected error occurred."
          },
          "default" : {
            "content" : {
              "text/plain" : {
                "schema" : {
                  "type" : "string"
                }
              }
            }
          }
        },
        "summary" : "Creates a token for accessing the REST API via username/password",
        "tags" : [ "Access" ]
      }
    }
}

swagger.json after change (excerpt)

{
   "/access/token" : {
      "post" : {
        "description" : "The token returned is formatted as a JSON Web Token (JWT). The token is base64 encoded and comprised of three parts. The header, the body, and the signature. The expiration of the token is a contained within the body. It is stored in the browser as a cookie, but also returned inthe response body to be stored/used by third party client scripts.",
        "operationId" : "createAccessToken",
        "requestBody" : {
          "content" : {
            "application/x-www-form-urlencoded" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "password" : {
                    "type" : "string"
                  },
                  "username" : {
                    "type" : "string"
                  }
                }
              }
            }
          }
        },
        "responses" : {
          "201" : {
            "content" : {
              "text/plain" : {
                "schema" : {
                  "type" : "string"
                }
              }
            }
          },
          "400" : {
            "description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."
          },
          "403" : {
            "description" : "Client is not authorized to make this request."
          },
          "409" : {
            "description" : "The request was valid but NiFi was not in the appropriate state to process it."
          },
          "500" : {
            "description" : "Unable to create access token because an unexpected error occurred."
          }
        },
        "summary" : "Creates a token for accessing the REST API via username/password",
        "tags" : [ "Access" ]
      }
    }
}

Tracking

Please complete the following tracking steps prior to pull request creation.

Issue Tracking

• Apache NiFi Jira issue created

Pull Request Tracking

• Pull Request title starts with Apache NiFi Jira issue number, such as NIFI-00000
• Pull Request commit message starts with Apache NiFi Jira issue number, as such NIFI-00000

Pull Request Formatting

• Pull Request based on current revision of the main branch
• Pull Request refers to a feature branch with one commit containing changes

Verification

Please indicate the verification steps performed prior to pull request creation.

Build

• Build completed using mvn clean install -P contrib-check
  • JDK 21

Licensing

• New dependencies are compatible with the Apache License 2.0 according to the License Policy
• New dependencies are documented in applicable LICENSE and NOTICE files

Documentation

• Documentation formatting appears as expected in rendered files

[exceptionfactory]

Thanks for working on this substantive adjustment @EndzeitBegins.

It seems like the best way to go, as it aligns the successful response type with the defined schema, as opposed to setting the default value.

Are you aware of any issues with removing the default response value as shown after these change?

[EndzeitBegins]

Thank you for your review @exceptionfactory.

I'm not aware of any significant issues arising from these changes.

As expected, the modifications primarily impact the generated documentation regarding responses and status codes, when comparing outputs from swagger-codegen and openapi-generator.

Notably, a few endpoints previously defined in the original swagger.json (prior to these changes) erroneously returned void despite the API actually providing valuable objects. With this PR applied, the generated code now correctly returns these objects:

• ProvenanceEventsApi
  • getInputContent
  • getOutputContent
• FlowFilesQueueApi
  • createDropRequest
  • createFlowFileListing
  • downloadFlowFileContent
• ProcessGroupsApi
  • createEmptyAllConnectionsRequest

Here an example of the generated code snippets.

Code generated before PR (excerpt)

    /**
     * Creates a request to drop the contents of the queue in this connection.
     * 
     * @param id The connection id. (required)
     * @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body
     * @http.response.details
     <table border="1">
       <caption>Response Details</caption>
        <tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
        <tr><td> 202 </td><td> The request has been accepted. A HTTP response header will contain the URI where the response can be polled. </td><td>  -  </td></tr>
        <tr><td> 400 </td><td> NiFi was unable to complete the request because it was invalid. The request should not be retried without modification. </td><td>  -  </td></tr>
        <tr><td> 401 </td><td> Client could not be authenticated. </td><td>  -  </td></tr>
        <tr><td> 403 </td><td> Client is not authorized to make this request. </td><td>  -  </td></tr>
        <tr><td> 404 </td><td> The specified resource could not be found. </td><td>  -  </td></tr>
        <tr><td> 409 </td><td> The request was valid but NiFi was not in the appropriate state to process it. </td><td>  -  </td></tr>
     </table>
     */
    public void createDropRequest(String id) throws ApiException {
        createDropRequestWithHttpInfo(id);
    }

Code generated after PR (excerpt)

    /**
     * Creates a request to drop the contents of the queue in this connection.
     * 
     * @param id The connection id. (required)
     * @return DropRequestEntity
     * @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body
     * @http.response.details
     <table border="1">
       <caption>Response Details</caption>
        <tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
        <tr><td> 202 </td><td> The request has been accepted. A HTTP response header will contain the URI where the response can be polled. </td><td>  -  </td></tr>
        <tr><td> 400 </td><td> NiFi was unable to complete the request because it was invalid. The request should not be retried without modification. </td><td>  -  </td></tr>
        <tr><td> 401 </td><td> Client could not be authenticated. </td><td>  -  </td></tr>
        <tr><td> 403 </td><td> Client is not authorized to make this request. </td><td>  -  </td></tr>
        <tr><td> 404 </td><td> The specified resource could not be found. </td><td>  -  </td></tr>
        <tr><td> 409 </td><td> The request was valid but NiFi was not in the appropriate state to process it. </td><td>  -  </td></tr>
     </table>
     */
    public DropRequestEntity createDropRequest(String id) throws ApiException {
        ApiResponse<DropRequestEntity> localVarResp = createDropRequestWithHttpInfo(id);
        return localVarResp.getData();
    }

This was the case, because they had both a success response (but without content) and a default response with content defined. Due to the success response being present, the content defined in the default response had no effect on the generated response type.

swagger.json before PR (excerpt)

    ...
    "/flowfile-queues/{id}/drop-requests" : {
      "post" : {
        "operationId" : "createDropRequest",
        ...
        "responses" : {
          "202" : {
            "description" : "The request has been accepted. A HTTP response header will contain the URI where the response can be polled."
          },
          "400" : {
            "description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."
          },
          "401" : {
            "description" : "Client could not be authenticated."
          },
          "403" : {
            "description" : "Client is not authorized to make this request."
          },
          "404" : {
            "description" : "The specified resource could not be found."
          },
          "409" : {
            "description" : "The request was valid but NiFi was not in the appropriate state to process it."
          },
          "default" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DropRequestEntity"
                }
              }
            }
          }
        },
        ...

swagger.json after PR (excerpt)

    ...
    "/flowfile-queues/{id}/drop-requests" : {
      "post" : {
        "operationId" : "createDropRequest",
        ...
        "responses" : {
          "202" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DropRequestEntity"
                }
              }
            },
            "description" : "The request has been accepted. A HTTP response header will contain the URI where the response can be polled."
          },
          "400" : {
            "description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."
          },
          "401" : {
            "description" : "Client could not be authenticated."
          },
          "403" : {
            "description" : "Client is not authorized to make this request."
          },
          "404" : {
            "description" : "The specified resource could not be found."
          },
          "409" : {
            "description" : "The request was valid but NiFi was not in the appropriate state to process it."
          }
        },
        ...
    },

[exceptionfactory]

Thanks for the reply and additional explanation @EndzeitBegins. Great to have these corrections and improvements to the OpenAPI specification! +1 merging