Avoid hardcoding Swagger information

[apupier]

from https://issues.jboss.org/browse/FUSETOOLS-3241

After creating an OpenApi definition with Apicurito, the use has the option to Generate a Fuse 7.1 Camel project based on the defined API.

The auto-generated Fuse project contains a REST DSL definition and uses the Maven dependency "camel-swagger-java-starter".

The skeleton created hardcodes the Swagger 2.0 information by loading the JSON definition in response to client requests. However the REST DSL is capable of auto-generating the Swagger information based on the REST DSL code. This allows dynamic Swagger documentation to be auto-generated when new REST operations are included in the DSL after the project has been created.

The following code is an extract from auto generating code from Apicurito:

        <rest id="rest1" path="/" enableCORS="true">
            <get id="openapi.json" produces="application/json" uri="openapi.json">
                <description>Gets the openapi document for this service</description>
                <route id="rest1-route1">
                    <setHeader id="setHeader-route1" headerName="Exchange.CONTENT_TYPE">
                        <constant>application/vnd.oai.openapi+json</constant>
                    </setHeader>
                    <setBody id="setBody-route1">
                       <!-- HERE --><simple>resource:classpath:openapi.json</simple><!-- HERE -->
                    </setBody>
                </route>
            </get>
        </rest>

[apupier]

@zregvart @EricWittmann does this request of modification make sense? is it a good idea to have it by default?

[apupier]

from Bruno Meseguer:

In Camel's REST DSL you can configure the apiContextPath, which is the context for Swagger to expose the autogenerated documentation, but the generator of APICURIO is bypassing the auto-documentation and serving the JSON file as if it was a service.

see https://issues.jboss.org/browse/FUSETOOLS-3241?focusedCommentId=13749896&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13749896

but what is the configuration of apiContextPath that we should provide? There is already one provided in restConfiguration

fuse-apicurito-generator/src/main/resources/camel-project-template/src/main/resources/spring/camel-context.xml

Line 21 in 3027c38

<restConfiguration component="servlet" apiContextPath="/openapi.json"/>

//cc @paoloantinori

[zregvart]

This was intentional, to serve the same OpenAPI document that the user provided. With the auto-generated document you loose some of the fidelity in the original OpenAPI document that was provided.

Drawing in @chirino who requested this.

[EricWittmann]

Yeah the use-case here is presumably when doing design-first API development. I would think you'd want the original OpenAPI document to be served, since it will contain more information than can be generated automatically. I don't know Fuse well enough to say, but there may be some mismatch between the definition and what the generated code actually does. That can happen when e.g. generating a JAX-RS project. Still, serving the original definition is usually what is desired.

[chirino]

Correct. The project was started design first, so we want to preserve as much info in the original as possible. It should be an intentional user action to convert to code first openapi doc generation.

It might be a nice feature of the tooling to provide a way convert a project between the two approaches.