swagger-api / swagger-api/swagger-codegen

[HTML2] deepObject parameter description is missing

Open
#11,896 0 comments 0 reactions 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

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:
image
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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.