OpenAPITools / OpenAPITools/openapi-generator

[Micronaut server] Add ability to exclude Swagger ApiOperation and ApiResponses annotation output from generated methods

Open
#12,223 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Leveraging release 5.4 ...

Given a yaml input document containing a snippet like the following ...

paths:
  /management/api/v1/users/{userId}:
    patch:
      x-codegen-request-body-name: message
      tags:
        - Backup Management Service
        - Backup Management Service Users
      summary: Update the specified user details
      description: Update the specified user details
      operationId: updateUserAsAdmin
      parameters:
        - name: userId
          in: path
          description: User identifier which may be extended format identifier e.g. machine:89928359235
          required: true
          schema:
            type: string
      requestBody:
        description: Details of user to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rest.UserUpdateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.UserResource'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '404':
          $ref: '#/components/responses/404-NotFound'

the generated java output looks something like ...

    /**
     * Update the specified user details
     * Update the specified user details
     *
     * @param userId User identifier which may be extended format identifier e.g. machine:89928359235 (required)
     * @param message Details of user to update (required)
     * @return RestUserResource
     */
    @ApiOperation(
        value = "Update the specified user details",
        nickname = "updateUserAsAdmin",
        notes = "Update the specified user details",
        response = RestUserResource.class,
        authorizations = {
            @Authorization(value = "bearerAuth")
        },
        tags={})
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "OK", response = RestUserResource.class),
        @ApiResponse(code = 401, message = "Unauthorized", response = RestError.class),
        @ApiResponse(code = 404, message = "Not Found", response = RestError.class)})
    @Patch(uri="/management/api/v1/users/{userId}")
    @Produces(value = {"application/json"})
    @Consumes(value = {"application/json"})
    public Mono<RestUserResource> updateUserAsAdminApi(
        @PathVariable(value="userId") @NotNull String userId, 
        @Body @NotNull @Valid RestUserUpdateRequest message
    ) {
        return updateUserAsAdmin(userId, message);
    }

It would be nice if there were a mechanism to exclude the generation of the ApiOperation and ApiResponses annotation output in the java. They yaml document is already the source of truth, duplicating the output in Java whilst nice also makes for massive Java files. In our case, we won't be generating from Java back to Yaml and have no need for those annotations to appear in the source.

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 locating the Micronaut server generator templates or generation logic that emits ApiOperation and ApiResponses, then inspect the generated method shown in the issue. Done means providing a mechanism to omit those annotations while retaining the other generated endpoint annotations and behavior; the payload does not name a specific file or test.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.