How to customize templates

[vladaman]

Is there any guide how to customize templates? Or even I'd like to pull code from git and modify library to fit out needs. I tried to import module runtime and development or event entire repo in IntelliJ but none of them seems to pickup the code generator process. Any way to link module to our app so we can alter some templates? What's the right setup? Thanks!

[ricardozanini]

Hi! You can't override the templates at this time. But it's an interesting feature to have.

What's your use case, so I can try to think on something.

[ricardozanini]

@vladaman, based on other issues you've opened, I assume you have a workaround? Additionally, can you share your use case for a need to override the templates?

[vladaman]

@ricardozanini well not yet. We are still trying to find "right" way of using Quarkus + AWS API Gateway (HTTP) + OpenAPI generator. We feel like if we'd have an option to edit generator templates it would help us. At least it would be welcomed to read a contribution guide how we can fork this repo and make changes. Frankly - I could not figure out how to even contribute. How to include a repository and where we can make changes.

In our case we'd like to use OAuth2 RBAC (so far we have not been able to figure out how to access JWT scope, but that's beyond this ticket - still struggling with this.). See https://quarkus.io/guides/security-oauth2.

AWS Api Gateway HTTP will export following schema and expects it with extensions:

  /app-user/{id}:
    get:
      operationId: "getAppUser"
      responses:
        default:
          description: "Default response for GET /app-user/{id}"
      security:
      - JWT-eu-cognito-pool:
        - "admin_write"
        - "test_read"
      x-amazon-apigateway-integration:
        payloadFormatVersion: "2.0"
        type: "aws_proxy"
        httpMethod: "POST"
        uri: "arn:aws:apigateway:me-south-1:lambda:path/2015-03-31/functions/arn:aws:lambda:me-south-1:xxxxxx:function:Tstlambda/invocations"
        connectionType: "INTERNET"

So how we'd modify the generator template is to include Quarkus compatible @RolesAllowed annotations like this:

    @RolesAllowed({"admin_write","test_read"}) // not generated from openapi
    @Override
    public AppUserResponse getAppUser(String id) {

Overall our goal is to use OpenAPI -> API Gateway + Cognito + JWT Token and run Quarkus as Lambda. Sounds like a common case. There is lots of documentation but getting it right requires lots of effort. Especially on security side. Still trying to resolve quarkusio/quarkus#24609 (comment)

[hbelmiro]

At least it would be welcomed to read a contribution guide how we can fork this repo and make changes.

Do you have a specific question on this @vladaman?
You just need to import the whole repo in your IDE, change the templates, install it on your maven repo, and you're ready to use it on your project.
The templates are located at https://github.com/quarkiverse/quarkus-openapi-generator/tree/main/deployment/src/main/resources/templates.

[ricardozanini]

At least it would be welcomed to read a contribution guide how we can fork this repo and make changes.

Honestly, I'd recommend not doing that. We can figure something out together, so you can extend the templates.

Frankly - I could not figure out how to even contribute. How to include a repository and where we can make changes.

There's no secret here. You fork, make your changes and submit a PR. The tricky thing is figuring out the architecture, as I understand can be troublesome sometimes. But the code is quite straightforward.

So how we'd modify the generator template is to include Quarkus compatible @RolesAllowed annotations like this:

For this case specifically, we should support out of the box. Our generator should add the @RolesAllowed annotation to the API file. Can you please open an issue? I'll track it there.

Regarding the templates, I think I can add this feature to the extension. You would add the template in your resources, pass it via properties, and we would replace yours during codegen. I'll use this issue to add this feature.

[KiMurray]

Was this feature to override templates added? I'm struggling to find documentation.
I'm looking to change the return types of each operation to Response. Also, we're using the jaxrs spec server generator and it has the config interfaceOnly, which does just this.

[hbelmiro]

@KiMurray this feature hasn't been added yet.

[ricardozanini]

@KiMurray, instead of overriding the template, I believe your use case can be solved by implementing a similar behavior of the jaxrs spec. We ignore the model defined in the OpenAPI file and use Response instead.

It's easier to implement, I'll track it in a new issue.