swagger-api / swagger-api/swagger-codegen

[Java - Spring] @Api 's description is not the designing tag's description

Open
#8,923 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mustache
Stars
17.8k
Forks
6k
PR merge metrics
No merged PRs in 30d

Description

Description

For the Petstore example, use the swagger.json generate spring api code, event using the SwaggerHub(https://app.swaggerhub.com) to export code, the @Api description is not the tags description .

swagger.json pet's description is "Everything about your Pets":

tags:
- name: pet
  description: Everything about your Pets
  externalDocs:
    description: Find out more
    url: http://swagger.io
- name: store
  description: Access to Petstore orders
- name: user
  description: Operations about user
  externalDocs:
    description: Find out more about our store
    url: http://swagger.io

But the api source code PetApi.java 's description is "the pet API",

@Api(value = "pet", description = "the pet API")
public interface PetApi {

}

and other *Api.java 's description is "the * API".

Is the tag's description never used?

Swagger-codegen version

2.3.1 and newer.
Also build with source code

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

Reproduce the Petstore example using swagger.json and the Spring export, then compare the tag description with the generated PetApi.java @Api description and the other *Api.java files. Trace how the generator handles tag descriptions and confirm that the completed change uses each tag's description instead of the generic "the * API" text.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi, spring
Domain
api, backend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 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.