swagger-api / swagger-api/swagger-codegen
[HTML2] deepObject parameter description is missing
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Description
Endpoint parameters of style deepObject dont have description in generated page. E.g. in declaration file:
"parameters": [
{
"name": "deepObject_parameter",
"in": "query",
"description": "Decription of deepObject parameter",
"style": "deepObject",
"schema": {
"$ref": "#/components/schemas/deepObjectSchema"
}
}
and deepObjectSchema:
"deepObjectSchema": {
"properties": {
"object1": {
"description": "Object one description.",
"type": "string"
},
"object2": {
"description": "Object two description.",
"type": "string"
}
},
"type": "object"
}
generate the following output in html page:

Where none of inlined deepObject parameter has any description, neither description of "deepObject_parameter" itself nor description of objects in "deepObjectSchema".
Swagger-codegen version
<groupId>io.swagger.codegen.v3</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>3.0.33</version>
Swagger declaration file content or url
Example json declaration file that reproduces the problem:
https://gist.github.com/pakhopav/73c3c6feabdf8e049b35eeaba73025d6
Command line used for generation
mvn -f pom-generators.xml io.swagger.codegen.v3:swagger-codegen-maven-plugin:generate
Steps to reproduce
Generate html page using declaration file provided by the gist link above.
Related issues/PRs
Suggest a fix/enhancement
Context for templates should have description data for deepObject parameters, that could be than accessed in
https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/resources/htmlDocs2/param.mustache template
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 with modules/swagger-codegen/src/main/resources/htmlDocs2/param.mustache and reproduce the issue using the declaration file from the linked gist and the provided Maven command. Trace how deepObject parameters reach the template, then verify that the generated HTML includes both the parameter description and descriptions for its inlined schema properties.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- html
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100