Fix Java OpenAPI generation for REST API

[longnguyen1997]

Description:

This PR modifies the OpenAPI YAML spec file in order to support Java REST client generation when using OpenAPITools/openapi-generator.

Notes for reviewer:

• The previous way of recording 400 errors was actually wrong: you were actually nesting a schema reference within an existing definition, so you ended up with the following.

400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/responses/InvalidParameterError'
              example:
                _status:
                  messages:
                    - message: "Invalid parameter: account.id"

became

400:
          description: Bad Request
          content:
            application/json:
              schema:
                description: Invalid parameter
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/Error'
                    example:
                      _status:
                        messages:
                          - message: "Invalid parameter: account.id"
                          - message: Invalid Transaction id. Please use \shard.realm.num-sss-nnn\ format where sss are seconds and nnn are nanoseconds
              example:
                _status:
                  messages:
                    - message: "Invalid parameter: account.id"

, which, of course, breaks the build when you do try to generate the client files. Doing this change resulted in much more consistent response code blocks (400s and 404s now share the same structure of pointing to a reference).

• Many of the responses outlined in the spec became InlineResponseXXX objects when generated, which is not good for naming. Screenshot included below. I moved these to their own reference names—this also keeps consistency with the overall structure of writing this spec file.

• We had to delete additional_properties from the spec for state proofs to get generation to work. According to the current alpha API for state proofs, there is no such property in the response, which might explain why it breaks generation.

Checklist

• Documented (Code comments, README, etc.)
• Tested (unit, integration, etc.)

[codecov]

Codecov Report

Merging #2447 (489cb5a) into main (545e340) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##               main    #2447   +/-   ##
=========================================
  Coverage     90.83%   90.83%           
  Complexity     2432     2432           
=========================================
  Files           420      420           
  Lines         11593    11593           
  Branches       1013     1013           
=========================================
  Hits          10530    10530           
  Misses          732      732           
  Partials        331      331           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 545e340...489cb5a. Read the comment docs.

[Nana-EC]

LGTM

[steven-sheehy]

This looks great. Do you mind adding the execution of the openapi generator so that we don't break you guys in the future? Something like this to hedera-mirror-rest/pom.xml:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi-generator.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/api/v1/openapi.yml</inputSpec>
                <generatorName>java</generatorName>
            </configuration>
        </execution>
    </executions>
</plugin>

[xin-hedera]

LGTM

[longnguyencircle]

Thank you all so much for the approvals! I'll be adding another commit with the actual generation execution @steven-sheehy mentioned.

[longnguyencircle]

Looks like the generation succeeded in REST API / test (v1) (pull_request)!

[INFO] writing file /home/runner/work/hedera-mirror-node/hedera-mirror-node/hedera-mirror-rest/target/generated-sources/openapi/src/main/java/org/openapitools/client/model/AccountsResponse.java
. . . . .

[steven-sheehy]

LGTM. Thanks!