Generator-jhipster: OpenApi exposed to swaggerUI

[vwiencek]

Hello,

I would like to propose 2 innovations for OpenAPI. According to jhipster documentation here it's possible to define API with .yml definition files (openApi 3 format). It might be interesting to have the 2 following features:

• expose generated API into swagger UI - with this we could see API generated from openApi generator next to the ones created during project scaffolding
• use OpenAPI generator to generate resources for jhipster native entities (User, Authority) and entities generated by JDL

Do these features make sense ?

• [X] Checking this box is mandatory (this is just to show you read everything)

[cbornet]

expose generated API into swagger UI - with this we could see API generated from openApi generator next to the ones created during project scaffolding

The generated AP should already be exposed in swagger UI by Springfox (provided the path is included in conf). Ideally we would serve directly the yaml file but I'm not sure it fits well with the generated endpoints or if the user adds spring controller by hand.
Note: if we talk about workflow and REPL, my personal preference is to use something such as swagger-ui-watcher to live reload a swagger-ui.

use OpenAPI generator to generate resources for jhipster native entities (User, Authority) and entities generated by JDL

This would be a two phase generation. Not sure there is a big gain. And the API-first is only an option.

[ecostanzi]

expose generated API into swagger UI - with this we could see API generated from openApi generator next to the ones created during project scaffolding

You could add a custom SwaggerCustomizer create another group matching only the basePath of the OpenApi Endpoint. From Jhipster 6 this the basepath of the OpenApi endpoints can be configured as a spring property: openapi._your-app-name_.basepath (see https://github.com/jhipster/generator-jhipster/issues/9555) and can be used to configure your custom Docket.

Alternatively, you can give a try to this jhipster module https://github.com/intesys/generator-jhipster-apiutils. It allows to expose the api.yml statically and serves it under a custom prompted path. The advantage in this case is that the yml is exactly the same as the one in you project. (I'm not sure, though, that swagger UI 2 can parse the yml file.)

[PierreBesson]

The feature would be interesting to have to push API first development. Personally I would be in favor of integrating most of the features from @ecostanzi module in the core of JHipster when the API first option is selected.

[ecostanzi]

I think that having the api.yml served separately is really useful, but this can be done only after the upgrade of swagger UI 2 to swagger UI 3 or rapidoc (the discussion is open at https://github.com/jhipster/generator-jhipster/issues/7966).

For now I coded swagger UI 3 in the module due to a lack of time. It was easier for me to deal with iframes than integrating react and angular components in the api/docs page.

[atomfrede]

I also found this quite interesting using webjars and static resources/html

[cbornet]

I also found this quite interesting using webjars and static resources/html

Yes, this is also valid with non-webjar swagger-ui. The point is to give the path to openapi.yml in the index.html.

[avdev4j]

Hi team,
I'm facing with the same issue than @vwiencek :
expose generated API into swagger UI - with this we could see API generated from openApi generator next to the ones created during project scaffolding

We could add a property in the api.yaml basepath to force the value to /api or add openapi.your-app-name.basepath to our properties with /api value too.

For the moment I wonder how to set a different value and still having the api available in the swagger-ui. I still looking for a solution.

The only thing I'm sure is that we need have a default conf or, at least, a documentation to expose our generated API in the ui.

regards,

[ecostanzi]

For the moment I wonder how to set a different value and still having the api available in the swagger-ui. I still looking for a solution.

@avdev4j you can create a new spring @Configuration file and add a new Docket bean:

@Bean
    public Docket businessDocket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("openapi")
                .forCodeGeneration(true)
                .directModelSubstitute(java.nio.ByteBuffer.class, String.class)
                .directModelSubstitute(URI.class, String.class)
                .directModelSubstitute(StatusType.class, Integer.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .securityContexts(securityContexts("/openapi-path.*"))
                .securitySchemes(Lists.newArrayList(jwtHeaderKey()))
                .additionalModels(typeResolver.resolve(Problem.class))
                .select()
                .paths(regex("/openapi-path.*"))
                .build();
        return docket;
    }

You can replace the /openapi-path.* with the property openapi.your-app-name.basepath.

Here's a full example: https://github.com/intesys/jhipsterconf2019-petstore-demo/blob/master/src/main/java/it/intesys/jhipetstore/config/CustomSwaggerConfiguration.java#L75

[avdev4j]

thanks @ecostanzi

After some searching, I think we have to :

• Add /api as default path in the generated api.yml. It match with JHipster default configuration.
• Add more documentation: docket config, spring configuration overriding...

By doing this we can cover the 2 ways, using the default JHipster basePath or define a specific one.

[pascalgrimaud]

Does someone want to start to work on this ? I can put a bounty if it can motivate people.
Otherwise, I'll close this, as it's opened for too long

[ecostanzi]

Hi, I can work on this but I didn't understand how we want to proceed.

@avdev4j PR helps the user to expose the generated endpoints under the /api path so that they are included in the swagger documentation.

Personally I like the idea of serving directly the openapi yml file without mixing the CRUD endpoints with the openapi endpoints. I'd avoid doing this with springfox dockets since we're planning to dismiss it un v7.

What do you think?

[avdev4j]

hi @pascalgrimaud
for me we had two things here :

• Put generated api under the default JHipster path /api (done by #10844)
• Add doc or add docket configuration to customize springfox.

EDIT: @ecostanzi If we planning to dismiss springfox, my second point is outdated. However I suggest to plan to do something to avoid having both generated api and native api in the same UI. It's not easy to read and not easy to understand.