swagger-api / swagger-api/swagger-codegen

[csharp][java] Generating api docs without model docs leads to broken doc links

Open
#5,732 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

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:

menubar_and_readme_md_-_swaggerclient_and_defaultgenerator_java_-_swagger-codegen_-____projects_swagger-codegen_

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.