Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Javadoc + operations interface + provider for state(ful/less) handlers #8346

Merged
merged 17 commits into from
Jan 19, 2021
Merged

Javadoc + operations interface + provider for state(ful/less) handlers #8346

merged 17 commits into from
Jan 19, 2021

Conversation

noordawod
Copy link
Contributor

@noordawod noordawod commented Jan 5, 2021

This pr brings the Undertow Server template up-to-date by adding the following:

  • Make the main class and methods abstract; this ensures that implementations do not miss an endpoint by mistake.
  • Added possibility to set a different base path if needed.
  • Added Javadoc for the endpoints, including description, notes, expects/returns and consumes/produces.
  • Properly links to other POJOs from the documentation.
  • Added licensing header to all files.
  • Fixed a couple of indentation errors in classes.
  • Allows users to just supply the implementation without the need to perform any modifications to the stock template.
  • Add @Nunnull annotations to the main generated class.

This could be a breaking change if one has forgotten to override an endpoint, so in many ways this pr helps users find such scenarios even before releasing to production.

@bbdouglas (2017/07) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01) @karismann (2019/03) @Zomzog (2019/04) @lwlee2608 (2019/10) @bkabrda (2020/01)

PR checklist

  • Read the contribution guidelines.
  • Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
  • If contributing template-only or documentation-only changes which will change sample output, build the project beforehand.
  • Run the shell script ./bin/generate-samples.shto update all Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*. For Windows users, please run the script in Git BASH.
  • File the PR against the correct branch: master, 5.1.x, 6.0.x
  • Copy the technical committee to review the pull request if your PR is targeting a particular programming language.

@noordawod
Copy link
Contributor Author

@wing328
Copy link
Member

wing328 commented Jan 7, 2021

@noordawod please run ./bin/generate-samples.sh to update the samples so that the CIs can verify the change.

@noordawod
Copy link
Contributor Author

noordawod commented Jan 7, 2021

@noordawod please run ./bin/generate-samples.sh to update the samples so that the CIs can verify the change.

Already did. No changes whatsoever in the samples.

The pr had already passed the CI tests (twice actually) so I think the failures aren't related to the pr.

@noordawod noordawod changed the title Added Javadoc + meta-data about request/response + abstract class. Javadoc + operations interface + provider for state(ful/less) handlers Jan 9, 2021
@noordawod
Copy link
Contributor Author

@wing328 could you please re-run the tests? as far as I can see, there was a problem downloading dependencies so would be nice to have all checks green.Thanks.

@noordawod
Copy link
Contributor Author

Bump @wing328 ?

@wing328
Copy link
Member

wing328 commented Jan 15, 2021

Just restarted the CircleCI job. Let's see how that goes.

@noordawod
Copy link
Contributor Author

[ERROR] Plugin org.codehaus.mojo:exec-maven-plugin:1.5.0 or one of its dependencies could not be resolved: Failed to read artifact descriptor for org.codehaus.mojo:exec-maven-plugin:jar:1.5.0: Could not transfer artifact org.codehaus.mojo:exec-maven-plugin:pom:1.5.0 from/to central (https://repo.maven.apache.org/maven2): Connection reset -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/PluginResolutionException

It's not even related...

@wing328
Copy link
Member

wing328 commented Jan 15, 2021

Saw that too.

I tried to test it locally (after updating the samples by running ./bin/generate-samples.sh ./bin/configs/other/java-undertow-server-java-undertow.yaml) but got the following errors:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.1:compile (default-compile) on project openapi-undertow-server: Compilation failure: Compilation failure: 
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[95,61] lambda expressions are not supported in -source 1.5
[ERROR]   (use -source 8 or higher to enable lambda expressions)
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[104,13] illegal start of expression
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[109,13] illegal start of expression
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[175,13] illegal start of expression
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[180,13] illegal start of expression
[ERROR] -> [Help 1]
[ERROR] 

Are you able to compile it locally without issue?

(Please also move the config file from ./bin/configs/other/java-undertow-server-java-undertow.yaml to ./bin/configs/java-undertow-server-java-undertow.yaml`, update the samples and commit the changes)

@wing328 wing328 added this to the 5.0.1 milestone Jan 15, 2021
@noordawod
Copy link
Contributor Author

noordawod commented Jan 15, 2021

Saw that too.

I tried to test it locally (after updating the samples by running ./bin/generate-samples.sh ./bin/configs/other/java-undertow-server-java-undertow.yaml) but got the following errors:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.1:compile (default-compile) on project openapi-undertow-server: Compilation failure: Compilation failure: 
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[95,61] lambda expressions are not supported in -source 1.5
[ERROR]   (use -source 8 or higher to enable lambda expressions)
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[104,13] illegal start of expression
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[109,13] illegal start of expression
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[175,13] illegal start of expression
[ERROR] /Users/williamcheng/Code/openapi-generator/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerProvider.java:[180,13] illegal start of expression
[ERROR] -> [Help 1]
[ERROR] 

Are you able to compile it locally without issue?

(Please also move the config file from ./bin/configs/other/java-undertow-server-java-undertow.yaml to ./bin/configs/java-undertow-server-java-undertow.yaml`, update the samples and commit the changes)

Thanks a bunch @wing328! I didn't notice that other/ folder so now at least I can see what's wrong. I'll patch everything and commit.

@noordawod
Copy link
Contributor Author

@wing328 now there's another problem:

anyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit
The command "docker pull swaggerapi/petstore" failed and exited with 1 during .

haha 😄

@noordawod
Copy link
Contributor Author

@wing328 so, what do you think is causing the CI to break?

@wing328
Copy link
Member

wing328 commented Jan 18, 2021

diff --git a/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerInterface.java b/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerInterface.java
index 41a18be4f1..6ea2e5ad8a 100644
--- a/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerInterface.java
+++ b/samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerInterface.java
@@ -541,10 +541,10 @@ public interface PathHandlerInterface {
      * <p><b>Response headers</b>: [CodegenProperty{openApiType&#x3D;&#39;integer&#39;, baseName&#x3D;&#39;X-Rate-Limit&#39;, complexType&#x3D;&#39;null&#39;, getter&#x3D;&#39;getxRateLimit&#39;, setter&#x3D;&#39;setxRateLimit&#39;, description&#x3D;&#39;calls per hour allowed by the user&#39;, dataType&#x3D;&#39;Integer&#39;, datatypeWithEnum&#x3D;&#39;Integer&#39;, dataFormat&#x3D;&#39;int32&#39;, name&#x3D;&#39;xRateLimit&#39;, min&#x3D;&#39;null&#39;, max&#x3D;&#39;null&#39;, defaultValue&#x3D;&#39;null&#39;, defaultValueWithParam&#x3D;&#39; &#x3D; data.X-Rate-Limit;&#39;, baseType&#x3D;&#39;Integer&#39;, containerType&#x3D;&#39;null&#39;, title&#x3D;&#39;null&#39;, unescapedDescription&#x3D;&#39;calls per hour allowed by the user&#39;, maxLength&#x3D;null, minLength&#x3D;null, pattern&#x3D;&#39;null&#39;, example&#x3D;&#39;null&#39;, jsonSchema&#x3D;&#39;{
   &quot;type&quot; : &quot;integer&quot;,
   &quot;format&quot; : &quot;int32&quot;
-}&#39;, minimum&#x3D;&#39;null&#39;, maximum&#x3D;&#39;null&#39;, exclusiveMinimum&#x3D;false, exclusiveMaximum&#x3D;false, required&#x3D;false, deprecated&#x3D;false, hasMoreNonReadOnly&#x3D;false, isPrimitiveType&#x3D;true, isModel&#x3D;false, isContainer&#x3D;false, isString&#x3D;false, isNumeric&#x3D;true, isInteger&#x3D;true, isLong&#x3D;false, isNumber&#x3D;false, isFloat&#x3D;false, isDouble&#x3D;false, isDecimal&#x3D;false, isByteArray&#x3D;false, isBinary&#x3D;false, isFile&#x3D;false, isBoolean&#x3D;false, isDate&#x3D;false, isDateTime&#x3D;false, isUuid&#x3D;false, isUri&#x3D;false, isEmail&#x3D;false, isFreeFormObject&#x3D;false, isArray&#x3D;false, isMap&#x3D;false, isEnum&#x3D;false, isReadOnly&#x3D;false, isWriteOnly&#x3D;false, isNullable&#x3D;false, isSelfReference&#x3D;false, isCircularReference&#x3D;false, isDiscriminator&#x3D;false, _enum&#x3D;null, allowableValues&#x3D;null, items&#x3D;null, additionalProperties&#x3D;null, vars&#x3D;[], requiredVars&#x3D;[], mostInnerItems&#x3D;null, vendorExtensions&#x3D;{}, hasValidation&#x3D;false, isInherited&#x3D;false, discriminatorValue&#x3D;&#39;null&#39;, nameInCamelCase&#x3D;&#39;XRateLimit&#39;, nameInSnakeCase&#x3D;&#39;X_RATE_LIMIT&#39;, enumName&#x3D;&#39;null&#39;, maxItems&#x3D;null, minItems&#x3D;null, maxProperties&#x3D;null, minProperties&#x3D;null, uniqueItems&#x3D;false, multipleOf&#x3D;null, isXmlAttribute&#x3D;false, xmlPrefix&#x3D;&#39;null&#39;, xmlName&#x3D;&#39;null&#39;, xmlNamespace&#x3D;&#39;null&#39;, isXmlWrapped&#x3D;false}, CodegenProperty{openApiType&#x3D;&#39;string&#39;, baseName&#x3D;&#39;X-Expires-After&#39;, complexType&#x3D;&#39;Date&#39;, getter&#x3D;&#39;getxExpiresAfter&#39;, setter&#x3D;&#39;setxExpiresAfter&#39;, description&#x3D;&#39;date in UTC when toekn expires&#39;, dataType&#x3D;&#39;Date&#39;, datatypeWithEnum&#x3D;&#39;Date&#39;, dataFormat&#x3D;&#39;date-time&#39;, name&#x3D;&#39;xExpiresAfter&#39;, min&#x3D;&#39;null&#39;, max&#x3D;&#39;null&#39;, defaultValue&#x3D;&#39;null&#39;, defaultValueWithParam&#x3D;&#39; &#x3D; data.X-Expires-After;&#39;, baseType&#x3D;&#39;Date&#39;, containerType&#x3D;&#39;null&#39;, title&#x3D;&#39;null&#39;, unescapedDescription&#x3D;&#39;date in UTC when toekn expires&#39;, maxLength&#x3D;null, minLength&#x3D;null, pattern&#x3D;&#39;null&#39;, example&#x3D;&#39;null&#39;, jsonSchema&#x3D;&#39;{
+}&#39;, minimum&#x3D;&#39;null&#39;, maximum&#x3D;&#39;null&#39;, exclusiveMinimum&#x3D;false, exclusiveMaximum&#x3D;false, required&#x3D;false, deprecated&#x3D;false, hasMoreNonReadOnly&#x3D;false, isPrimitiveType&#x3D;true, isModel&#x3D;false, isContainer&#x3D;false, isString&#x3D;false, isNumeric&#x3D;true, isInteger&#x3D;true, isLong&#x3D;false, isNumber&#x3D;false, isFloat&#x3D;false, isDouble&#x3D;false, isDecimal&#x3D;false, isByteArray&#x3D;false, isBinary&#x3D;false, isFile&#x3D;false, isBoolean&#x3D;false, isDate&#x3D;false, isDateTime&#x3D;false, isUuid&#x3D;false, isUri&#x3D;false, isEmail&#x3D;false, isFreeFormObject&#x3D;false, isArray&#x3D;false, isMap&#x3D;false, isEnum&#x3D;false, isReadOnly&#x3D;false, isWriteOnly&#x3D;false, isNullable&#x3D;false, isSelfReference&#x3D;false, isCircularReference&#x3D;false, isDiscriminator&#x3D;false, _enum&#x3D;null, allowableValues&#x3D;null, items&#x3D;null, additionalProperties&#x3D;null, vars&#x3D;[], requiredVars&#x3D;[], mostInnerItems&#x3D;null, vendorExtensions&#x3D;{}, hasValidation&#x3D;false, isInherited&#x3D;false, discriminatorValue&#x3D;&#39;null&#39;, nameInCamelCase&#x3D;&#39;XRateLimit&#39;, nameInSnakeCase&#x3D;&#39;X_RATE_LIMIT&#39;, enumName&#x3D;&#39;null&#39;, maxItems&#x3D;null, minItems&#x3D;null, maxProperties&#x3D;null, minProperties&#x3D;null, uniqueItems&#x3D;false, multipleOf&#x3D;null, isXmlAttribute&#x3D;false, xmlPrefix&#x3D;&#39;null&#39;, xmlName&#x3D;&#39;null&#39;, xmlNamespace&#x3D;&#39;null&#39;, isXmlWrapped&#x3D;false, isNull&#x3D;false}, CodegenProperty{openApiType&#x3D;&#39;string&#39;, baseName&#x3D;&#39;X-Expires-After&#39;, complexType&#x3D;&#39;Date&#39;, getter&#x3D;&#39;getxExpiresAfter&#39;, setter&#x3D;&#39;setxExpiresAfter&#39;, description&#x3D;&#39;date in UTC when toekn expires&#39;, dataType&#x3D;&#39;Date&#39;, datatypeWithEnum&#x3D;&#39;Date&#39;, dataFormat&#x3D;&#39;date-time&#39;, name&#x3D;&#39;xExpiresAfter&#39;, min&#x3D;&#39;null&#39;, max&#x3D;&#39;null&#39;, defaultValue&#x3D;&#39;null&#39;, defaultValueWithParam&#x3D;&#39; &#x3D; data.X-Expires-After;&#39;, baseType&#x3D;&#39;Date&#39;, containerType&#x3D;&#39;null&#39;, title&#x3D;&#39;null&#39;, unescapedDescription&#x3D;&#39;date in UTC when toekn expires&#39;, maxLength&#x3D;null, minLength&#x3D;null, pattern&#x3D;&#39;null&#39;, example&#x3D;&#39;null&#39;, jsonSchema&#x3D;&#39;{
   &quot;type&quot; : &quot;string&quot;,
   &quot;format&quot; : &quot;date-time&quot;
-}&#39;, minimum&#x3D;&#39;null&#39;, maximum&#x3D;&#39;null&#39;, exclusiveMinimum&#x3D;false, exclusiveMaximum&#x3D;false, required&#x3D;false, deprecated&#x3D;false, hasMoreNonReadOnly&#x3D;false, isPrimitiveType&#x3D;false, isModel&#x3D;false, isContainer&#x3D;false, isString&#x3D;false, isNumeric&#x3D;false, isInteger&#x3D;false, isLong&#x3D;false, isNumber&#x3D;false, isFloat&#x3D;false, isDouble&#x3D;false, isDecimal&#x3D;false, isByteArray&#x3D;false, isBinary&#x3D;false, isFile&#x3D;false, isBoolean&#x3D;false, isDate&#x3D;false, isDateTime&#x3D;true, isUuid&#x3D;false, isUri&#x3D;false, isEmail&#x3D;false, isFreeFormObject&#x3D;false, isArray&#x3D;false, isMap&#x3D;false, isEnum&#x3D;false, isReadOnly&#x3D;false, isWriteOnly&#x3D;false, isNullable&#x3D;false, isSelfReference&#x3D;false, isCircularReference&#x3D;false, isDiscriminator&#x3D;false, _enum&#x3D;null, allowableValues&#x3D;null, items&#x3D;null, additionalProperties&#x3D;null, vars&#x3D;[], requiredVars&#x3D;[], mostInnerItems&#x3D;null, vendorExtensions&#x3D;{}, hasValidation&#x3D;false, isInherited&#x3D;false, discriminatorValue&#x3D;&#39;null&#39;, nameInCamelCase&#x3D;&#39;XExpiresAfter&#39;, nameInSnakeCase&#x3D;&#39;X_EXPIRES_AFTER&#39;, enumName&#x3D;&#39;null&#39;, maxItems&#x3D;null, minItems&#x3D;null, maxProperties&#x3D;null, minProperties&#x3D;null, uniqueItems&#x3D;false, multipleOf&#x3D;null, isXmlAttribute&#x3D;false, xmlPrefix&#x3D;&#39;null&#39;, xmlName&#x3D;&#39;null&#39;, xmlNamespace&#x3D;&#39;null&#39;, isXmlWrapped&#x3D;false}]</p>
+}&#39;, minimum&#x3D;&#39;null&#39;, maximum&#x3D;&#39;null&#39;, exclusiveMinimum&#x3D;false, exclusiveMaximum&#x3D;false, required&#x3D;false, deprecated&#x3D;false, hasMoreNonReadOnly&#x3D;false, isPrimitiveType&#x3D;false, isModel&#x3D;false, isContainer&#x3D;false, isString&#x3D;false, isNumeric&#x3D;false, isInteger&#x3D;false, isLong&#x3D;false, isNumber&#x3D;false, isFloat&#x3D;false, isDouble&#x3D;false, isDecimal&#x3D;false, isByteArray&#x3D;false, isBinary&#x3D;false, isFile&#x3D;false, isBoolean&#x3D;false, isDate&#x3D;false, isDateTime&#x3D;true, isUuid&#x3D;false, isUri&#x3D;false, isEmail&#x3D;false, isFreeFormObject&#x3D;false, isArray&#x3D;false, isMap&#x3D;false, isEnum&#x3D;false, isReadOnly&#x3D;false, isWriteOnly&#x3D;false, isNullable&#x3D;false, isSelfReference&#x3D;false, isCircularReference&#x3D;false, isDiscriminator&#x3D;false, _enum&#x3D;null, allowableValues&#x3D;null, items&#x3D;null, additionalProperties&#x3D;null, vars&#x3D;[], requiredVars&#x3D;[], mostInnerItems&#x3D;null, vendorExtensions&#x3D;{}, hasValidation&#x3D;false, isInherited&#x3D;false, discriminatorValue&#x3D;&#39;null&#39;, nameInCamelCase&#x3D;&#39;XExpiresAfter&#39;, nameInSnakeCase&#x3D;&#39;X_EXPIRES_AFTER&#39;, enumName&#x3D;&#39;null&#39;, maxItems&#x3D;null, minItems&#x3D;null, maxProperties&#x3D;null, minProperties&#x3D;null, uniqueItems&#x3D;false, multipleOf&#x3D;null, isXmlAttribute&#x3D;false, xmlPrefix&#x3D;&#39;null&#39;, xmlName&#x3D;&#39;null&#39;, xmlNamespace&#x3D;&#39;null&#39;, isXmlWrapped&#x3D;false, isNull&#x3D;false}]</p>
      *
      * <p><b>Produces</b>: [{mediaType=application/xml}, {mediaType=application/json}]</p>
      * <p><b>Returns</b>: {@link String}</p>
Perform git status
On branch noordawod-undertow-update/javadoc-and-make-abstract2
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   samples/server/petstore/java-undertow/src/main/java/org/openapitools/handler/PathHandlerInterface.java

no changes added to commit (use "git add" and/or "git commit -a")

Please update the samples.

@noordawod
Copy link
Contributor Author

This is utterly strange, I did that already. Trying again...

mvn clean package -DskipTests=true && ./bin/utils/ensure-up-to-date && mvn clean package -DskipTests=true && ./bin/generate-samples.sh bin/configs/java-*

@noordawod
Copy link
Contributor Author

noordawod commented Jan 18, 2021

@wing328

Sorry mate, but this is not a samples problem. There's something else going on, just look at the log.

I even regenerated all samples again locally just to be sure no changes happened:

$ mvn clean package -DskipTests=true && ./bin/utils/ensure-up-to-date && mvn clean package -DskipTests=true && ./bin/generate-samples.sh bin/configs/java-*

...
...
...
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
################################################################################
[pool-1-thread-19] Finished generating java…
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
################################################################################
[pool-1-thread-20] Finished generating java…
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
################################################################################
[pool-1-thread-10] Finished generating java…
[SUCCESS] Batch generation finished 40 generators successfully.

$ git status 
Refresh index: 100% (27301/27301), done.
On branch undertow-update/javadoc-and-make-abstract
Your branch is up to date with 'origin/undertow-update/javadoc-and-make-abstract'.

nothing to commit, working tree clean

@wing328
Copy link
Member

wing328 commented Jan 19, 2021

@wing328 wing328 merged commit f5c4960 into OpenAPITools:master Jan 19, 2021
@noordawod
Copy link
Contributor Author

Perfect, thanks for the help!
Another pr is coming sometime soon to upgrade the Kotlin/Ktor to recent dependencies and tooling.

@noordawod noordawod deleted the undertow-update/javadoc-and-make-abstract branch January 19, 2021 05:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants