swagger-api / swagger-api/swagger-codegen
[Java] [Nice-To-Have-Feature] Tags description and externalDocs output in the *Api.java Class comment
Open
Nobody has claimed this yet.
Client: Java
Enhancement: General
Feature: Documentation
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
For the tags in the spec
"tags": [
{
"description": "Everything about your Pets",
"externalDocs": {
"description": "Find out more",
"url": "http://swagger.io"
},
"name": "pet"
}
It will be nice to display the description and externalDocs in the Java source comment, as below:
/**
* Everything about your Pets
* @see <a href="http://swagger.io">Find out more</a>
*/
@javax.annotation.Generated(value = "class io.swagger.codegen.languages.JavaClientCodegen", date = "2016-03-24T09:40:51.034-07:00")
public class PetApi {
private ApiClient apiClient;
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the Java *Api.java generation template and the tag-rendering path in this template-driven code generator. Use the supplied OpenAPI tags example to trace the generated class comment, then verify that tag descriptions and externalDocs appear in the expected JavaDoc format.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100