OpenAPITools / OpenAPITools/openapi-generator

[Java] Can't genereate code with OpenApi 3 Annotations (Springboot)

Open
#8,406 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Description

Hello, I am using the generator in a java project (Springboot Application) and want it to generate the code with Annotations for openapi 3.0 instead of swagger.
After searching for a longer period of time I could not find any information on how tow do that.
Is there a setting that i can change to achieve this or do i need to use a different version / product branch?

As I use the generated code to generate my openapi 3.0 documentation I struggle with missing information in the endpoint documentation, such as the different responses and codes that i have defined.

If there is anything that is not clear or that i have done wrong in this issue, please let me know. It is the first issue I made and as such might not be too good.

openapi-generator version

Using version 5.0.0 of the "openapi-generator-maven-plugin"

OpenAPI declaration file content or url
openapi: 3.0.3
info:
  version: 1.0.0
  title: ABC
  description: Miscellaneous endpoints for all apps and clients
servers:
  - url: http://localhost:3002/app-gateway-api-doc
    description: local dev server
paths:
  /knock-knock:
    get:
      description: Check connection and get the name of the server
      operationId: knockKnock
      parameters:
        - $ref: "#/components/parameters/language"
      responses:
        "200":
          description: knock knock response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KnockKnockResponse"
        "400":
          description: "User not authorized"
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
components:
  parameters:
    language:
      name: language
      description: 2-letter language code
      in: query
      schema:
          $ref: "#/components/schemas/Language"
  schemas:
    KnockKnockResponse:
      type: object
      description: A simple response for clients to check, if the server is online, test,
        if the auth token is still valid.
      required:
        - whoIsThere
      properties:
        whoIsThere:
          type: string
          description: Name of server
          example: Springboot Example, Server xy, v1.0.6
    RestError:
      type: object
      description: Default API error model
      required:
        - type
        - message
      properties:
        message:
          type: string
          description: The error message
          example: There is no resource for path /404
        errorType:
          type: string
          description: Type of error
          example: UnknownResourceError
        additionalProperties:
          type: array
          description: Key/value array to transport additional error information
          items:
            $ref: "#/components/schemas/RestErrorAdditionalProperty"
    RestErrorAdditionalProperty:
      type: object
      description: Key/value object to transport additional error information
      required:
        - key
        - value
      properties:
        key:
          type: string
          example: foo
        value:
          type: string
          example: bar
    Language:
      type: string
      description: 2-letter language code
      default: de
      enum: [de, fr, it, en]
Command line used for generation

Using Maven to build the project.
mvn clean install

Steps to reproduce
  1. configure the plugin to use a simple example yaml
  2. Do a maven clean install
  3. look at the generated Api File and check if the methods have openapi 3.0 annotations or just swagger

Example of my plugin configuration for this.

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>4.2.3</version>
  <executions>
    <execution>
      <id>spring-boot-api</id>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
	  <skip>false</skip>
	  <inputSpec>${project.basedir}/src/main/resources/openapi/knock.yaml</inputSpec>
	  <generatorName>spring</generatorName>
	  <configOptions>
            <dateLibrary>joda</dateLibrary>
            <interfaceOnly>true</interfaceOnly>
	  </configOptions>
	  <library>spring-boot</library>
	  <apiPackage>ch.company.project.knock.api</apiPackage>
	  <modelPackage>ch.company.project.knock.api.model</modelPackage>
      </configuration>
    </execution>
  </executions>
</plugin>
Related issues/PRs
Suggest a fix/enhancement

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the Maven generation with the supplied OpenAPI YAML, spring generator configuration, and openapi-generator-maven-plugin versions, then inspect the generated Api file's annotations. Compare the generated Swagger annotations with the requested OpenAPI 3 annotations and verify whether response codes and descriptions are present. Done means the documented configuration or generated output provides the requested OpenAPI 3 endpoint annotations.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi, spring-boot
Domain
api, backend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.