swagger-api / swagger-api/swagger-codegen

[Javascript] Doc output contains broken links to models for primitive types

Open
#9,473 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

When I have a parameter that takes an array of Strings, the output documentation creates a broken link to String.md that does not exist, as though String was a model.

For example, the pet store example's GET /pet/findByTags method has this parameter:

"parameters": [
  {
    "name": "tags",
    "in": "query",
    "description": "Tags to filter by",
    "required": true,
    "type": "array",
    "items": {
      "type": "string"
    },
    "collectionFormat": "multi"
  }
],

When I generate with the Docker container swaggerapi/swagger-codegen-cli:2.4.5, I get this output in docs/PetApi.md:

### Parameters


Name | Type | Description
------------- | ------------- | -------------
 tags (required) | [[String]](String.md)| Tags to filter by 

That link to String.md is broken because String is not a model type.

This might be related to #7291.

Swagger-codegen version

Docker container swaggerapi/swagger-codegen-cli:2.4.5.

Swagger declaration file content or url

https://petstore.swagger.io/v2/swagger.json

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

Generate the petstore documentation with swaggerapi/swagger-codegen-cli:2.4.5 using the linked Swagger declaration, then inspect docs/PetApi.md for the tags parameter output. Trace the documentation generation path responsible for the [String] link; done means primitive array types no longer link to nonexistent model pages.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.