swagger-api/swagger-codegen

RxJava2 with retrofit2 generates wrong md doc

Open

#6964 opened on Nov 15, 2017

View on GitHub
 (2 comments) (0 reactions) (0 assignees)HTML (12,701 stars) (5,474 forks)batch import
Client: JavaEnhancement: FeatureFeature: Documentationhelp wanted

Description

Description

When I generate a Java client with {"useRxJava2":"true", "library":"retrofit2"} the generated docs are wrong, they don't match the api. Looks like it's just the standard java md-doc without the rxJava enhancements.

Swagger-codegen version

Version: 2.2.3 and 3.0.0-SNAPSHOT

Swagger declaration file content or url

can use Uber or any other example

Command line used for generation

java -jar /Users/rainer/bin/swagger-codegen-cli-2.2.3.jar generate -l java -o rx -i swagger.yaml -c rc2.cnf

rc2.cnf: {"useRxJava2":"true", "library":"retrofit2"}

Steps to reproduce
  1. Generate code and look into the docs directory.
  2. md doc doesn't match (no Observables) the generated rx java api code.
Related issues/PRs
Suggest a fix/enhancement

Thanks, Rainer Feike

Contributor guide

Tech stack
java
Domain
documentationapi
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
3-5 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
JavaSwagger/OpenAPITemplate engines (Mustache)RxJava basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
30
Research direction
Investigate the mustache templates used for generating Markdown documentation in the swagger codegen project. Focus on how RxJava2 types are handled in the Java client generator with the 'useRxJava2' and 'library:retrofit2' options. The bug report indicates that the generated docs do not show Observables in the API signatures. Check the template files under modules/swagger codegen/src/main/resources/Java/libraries/retrofit2/ and look for a template that generates API documentation (likely a .md file). Compare with the non RxJava version to identify missing sections. Additionally, review any existing comments in the issue for potential fixes or hints.