swagger-api / swagger-api/swagger-codegen
[csharp][java] Generating api docs without model docs leads to broken doc links
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Description
DefaultGenerator allows for generating api docs without model docs, and model docs without api docs. Templates for csharp, java, and possibly others make the assumption these are always generated together. I discovered this while creating a new generator and looking at how doc templates are done in existing generators.
Swagger-codegen version
All versions supporting api/model docs.
Swagger declaration file content or url
N/A
Command line used for generation
N/A
Steps to reproduce
# NOTE: You have to delete existing docs, otherwise old model docs still "work"
\rm -rf samples/client/petstore/csharp/SwaggerClient/docs
JAVA_OPTS="$JAVA_OPTS -DmodelDocs=false" ./bin/csharp-petstore.sh
git status
You'll notice after running git status that all model documentation is marked for deletion.
In C#, the README will reference files that no longer exist:
In addition to README, api docs point back to the model documentation section from the above screenshot:
[[Back to Model list]](../README.md#documentation-for-models)
As well as linking to missing parameter models:
### Parameters
Name | Type | Description | Notes
------------- | ------------- | ------------- | -------------
**body** | [**Pet**](Pet.md)| Pet object that needs to be added to the store |
and return types:
### Return type
[**ApiResponse**](ApiResponse.md)
Related issues
N/A
Suggest a Fix
As part of #5731, I've added the global additionalProperties: generateApiDocs and generateModelDocs. In that PR, I've used these to conditionally modify parameters, return types, and README sections to avoid generating broken links.
For example (from linked Kotlin client PR):
### Return type
{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}{{#generateModelDocs}}[**{{returnType}}**]({{returnBaseType}}.md){{/generateModelDocs}}{{^generateModelDocs}}**{{returnType}}**{{/generateModelDocs}}{{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}}
This should be an easy modification after PR #5731 is merged and the template properties are available. We'll probably want to list affected generator documentation templates as a TODO in this description.
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 DefaultGenerator and the C# and Java documentation templates, then reproduce the issue with samples/client/petstore/csharp/SwaggerClient and bin/csharp-petstore.sh using modelDocs=false. Check README and API documentation links when model docs are disabled; done means generated output contains no links to missing model documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, java
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100