swagger-api/swagger-codegen

Code/Architecture needs documentation

Open

#2,104 opened on Feb 10, 2016

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

Description

As a Java developer trying to contribute some code, I must say that I find it quite hard to orientate myself in the code base.

The README.md has mainly information about the actual usage, and CONTRIBUTING.md has some generic advice.

What I'm missing is a general overview how the code generation (and the configuration) works (the non-language-specific parts). It also doesn't help that most classes and methods don't have any Javadoc, which makes finding out what they are for quite hard.

Could the people who understand how it works please invest some time to write a general overview and Javadocs for the classes in the main package (io.swager.codegen)?

For the current example: I wanted to finally fix #1255 (which I opened myself back in september). I figured out I would add fields modelNamePrefix and modelNameSuffix in DefaultCodeGen, and use them in toModelName (and maybe also toModelFileName?). So far, so easy. The hard part now is figuring out how to get those values into this class from the maven plugin or the CLI.

It looks like some parameters are passed via additionalProperties, others are passed via dedicated setters from outside. To fill additionalProperties from the command line, there is the --additionalProperties option defined in io.swagger.codegen.cmd.Generate, but the Maven-Plugin seems to not support that. Also, CLI seems to use the CodegenConfigurator, which then creates a ClientOptInput, which is passed to a DefaultGenerator. The ClientOptInput contains both a ClientOpts object and a CodegenConfig object, and the additional options are passed from the former into the latter. Though in the CodegenMojo, the additional properties are directly set in the CodegenConfig object (but only some special-cased ones and those which are declared by the CodegenConfig implementation as cliOption and passed to the maven-plugin as configOptions).

Sorry, I can't see any real sense in all this. Can someone help me figure this out? (If someone explains it to me, I can also help to document it, or refactor it so it gets clearer.)

Contributor guide

Tech stack
java
Domain
documentationdeveloper experience
Issue type
documentation
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.
over 1 week
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
JavaUnderstanding of Swagger/OpenAPI
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
30
Research direction
The issue requests a general overview of the code generation architecture and Javadoc for classes in the main package (io.swagger.codegen). Key files to consider are README.md, CONTRIBUTING.md, and the code generation classes such as DefaultCodeGen, toModelName, toModelFileName, io.swagger.codegen.cmd.Generate, CodegenConfigurator, ClientOptInput, DefaultGenerator, ClientOpts, CodegenConfig, and CodegenMojo. To address this, one should document the flow from CLI/Maven plugin to code generation, and add Javadoc to public methods. The maintainer comments suggest a need for clearer structure.