Search code examples
javaopenapihelidon

Automatic add openapi file in helidon project

I want instrument for automatic generate openapi in my helidon project (Java 1.8, helidon SE 1.3.1)

I read documenttation/example and make:

  1. add depends in maven
  2. add openapi.yml in META-INF
  3. add endpoint for router.
  4. add apifilter and apimodelreader

pom.xml:

<dependency>
   <groupId>io.helidon.openapi</groupId>
   <artifactId>helidon-openapi</artifactId>
   <version>1.3.1</version>
</dependency>

main.java:

return Routing.builder()
                .register(JsonSupport.create())
                .register(health)                   // Health at "/health"
                .register(metrics)                  // Metrics at "/metrics"
                .register("/file", fileService)
                .register("/card", cardService)
                .register(OpenAPISupport.create(config))
                .build();

application.yaml

openapi:
  filter: ru.ittest.feezio.openapi.SimpleAPIFilter
  model:
    reader: ru.ittest.feezio.openapi.SimpleAPIModelReader

Now I have openapi document in endpoint: http://127.0.0.1:8456/openapi And it is my openapi.yml. But I don't want write by hand openapi.yml, I want auto generate yml for my classes: fileService and cardService. This classes work and response success (API work, I make documentation now)

Solution

  • As the OP noted, Helidon SE cannot automatically generate the OpenAPI document for your app. You provide either a static openapi.yml file or your own model reader and/or filter classes. You can provide the static file and the classes if you want to but that is not required. For other interested readers here's the doc.

    Probably most developers who want OpenAPI support in their Helidon SE app will use a tool to define their API and then export the OpenAPI document from the tool, adding that YAML file to their application JAR (typically at META-INF/openapi.yml).

    Note that if you use Helidon MP (which implements MicroProfile OpenAPI) and add the normal JAX-RS annotations to your endpoints, then Helidon MP can generate the OpenAPI document for you automatically. Here's the doc for that.