search

swagger-api / swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
http://swagger.io
Apache License 2.0
17.03k stars 6.03k forks source link

3.0.0 server-code generation always failing due to missing /<backend>/model.mustache #7622

Closed asnowfix closed 6 years ago

asnowfix commented 6 years ago
Description

I am trying to generate server-side code out of a open api 3.0 specification. I tried the 2 backends that seems to be available in 3.0.0-rc0 (jaxrs & nodejs-server), with the same output error pattern: a missing Mustache.io file.

Caused by: java.io.FileNotFoundException: /JavaJaxRS/model.mustache
Swagger-codegen version

I am using 3.0.0-rc0 downloaded using wget. This is not a regression, as far as I can tell.

Swagger declaration file content or url

https://github.com/openservicebrokerapi/servicebroker/blob/master/openapi.yaml

Command line used for generation
java -jar swagger-codegen-cli.jar generate --lang=jaxrs --output=. --input-spec=api/openapi.yaml --group-id=com.hp.gdrs --artifact-id=aws-cf-service-broker --api-package=com.
hp.gdrs.osb.api --model-package=com.hp.gdrs.osb.model
Steps to reproduce
  1. Download the Open Service Broker specification as YAML
  2. Run swagger-codegen on the above YAML
Related issues/PRs

Related issue might be completion of the support of OpenAPI 3.0 support in https://github.com/swagger-api/swagger-codegen/issues/6598

Suggest a fix/enhancement
HugoMario commented 6 years ago

Hey @asnowfix sorry for delay response.

Right now swagger-codegen 3.0.0 is supporting java language for client and inflector language for server. That's the main reason the template is not found.

We can keep this issue open till jaxrs be implemented.

jmini commented 6 years ago

Is there a description of the necessary steps to convert a Swagger 2.0 generator to an OpenAPI 3.0 generator? Even a raw TODO list with the main steps would be sufficient to start.

We would also like to have a jaxrs backend for our application. For the moment we are using a OpenAPI 3.0.1 Spec, but for code-generation and runtime we have converted it back to Swagger 2.0.

HugoMario commented 6 years ago

@jmini no really, i mean there is not a formal document about it, but right now the steps are:

Anyway, on next days i'll work on a wiki to describe these steps with more details.

jmini commented 6 years ago

@asnowfix: From the v3.0.0-rc0 releases notes:

Known Limitations java and inflector are the only supported languages.

I am (mis)using this issue to discuss how we can move forward for the jaxrs generator (name might change to jaxrs-jersey)

@HugoMario:

Thank you a lot for those pointers.

In order to create the templates, for the moment I have just copied the one from swagger-codegen repo from the master branch (path: /modules/swagger-codegen/src/main/resources/JavaJaxRS)

I did some modifications (some small syntax changes, analog the one you have made in the swagger-codegen-generators). See Swagger Codegen migration from Mustache and Handlebars templates.. See also https://github.com/swagger-api/swagger-codegen/issues/3950 for some background about it.

Blank spaces in the generated code

For the moment I did not investigate the blank spaces issue. I should add some ~ to get some better generated code. But for the moment the important result is that the generated code can be compiled. I think that we will format our code with the Eclipse Java Formatter (in order to have something consistent with the rest of our codebase). The blank spaces introduced by handlebar are not an issue for us.

Result

I have pushed the result to this branch on my fork: https://github.com/jmini/swagger-codegen-generators/tree/jaxrs

I am now capable to generate the jaxrs-jersey code.

NOTE: there is no integration with the CLI or the Maven plugin yet. To start the generator you can use something like this:

CodegenConfigurator configurator = new CodegenConfigurator();
configurator.setLang("jaxrs"); //TODO: will probably be jaxrs-jersey
configurator.setInputSpec("<path to your spec>/openapi-spec.json");
final ClientOptInput input = configurator.toClientOptInput();

JavaJerseyServerCodegen config = new io.swagger.codegen.languages.java.JavaJerseyServerCodegen();
config.setOutputDir("generated-code2");
config.setJava8Mode(true);
input.setConfig(config);

new DefaultGenerator().opts(input).generate();

NOTE: the result still works with Swagger 2 at runtime! The generated code has a dependency on io.swagger:swagger-jersey2-jaxrs:1.5.18. The output is similar to what the current swagger-codegen(version 2.3.1) is generating. But it takes a OpenAPI 3.0.1 spec as input (the same we use for the java client) and we benefit from the fixes made in the generator for the java-client.

I think this is great as first step!

@asnowfix: Are you interesting by this approach? If yes, tell me if you need anything to test it.

Redundancy in the templates?

@HugoMario: I have the feeling that there is a lot of redundancy in the different mustache templates. When I look at the work you did in the inflector generator, I have the feeling this should also be made in the jaxrs-* templates.

Have you a strategy for this?

Moving to swagger v3 for jaxrs at runtime?

@HugoMario: I assume you the goal is to get a jaxrs-jersey code generator that will depend from io.swagger.core.v3:swagger-jersey2-jaxrs or something like that. But this module should be in the swagger-core repository in the 2.0 branch. I could not find it. https://github.com/swagger-api/swagger-core/tree/2.0/modules

This is probably to early. What is the vision here?

Pull Request for swagger-codegen-generators?

@HugoMario: I assume you do not want any generator that generates code for an old version of swagger at runtime in the swagger-codegen-generators repo. So I did not open any merge request at the moment.

My plan is to continue to maintain my branch, until there is a solution for jaxrs-jersey that works at runtime with swagger v3 and the appropriate generator for it.

Please tell me what you think.

jmini commented 6 years ago

@HugoMario:

add new/updated generator class to CodegenConfig file.

In my opinion this CodegenConfig is not implemented the way it should. Each project containing some generators should register them separately. java and inflector now lives in a new jar and the service registery should reflect that:

jmini commented 6 years ago

Redundancy in the templates?

I have found this discussion: #4937 and I propose to continue it there.

jmini commented 6 years ago

@HugoMario:

Anyway, on next days i'll work on a wiki to describe these steps with more details.

I have started something: Swagger Codegen migration (swagger codegen generators repository)

HugoMario commented 6 years ago

sounds good, thanks. I'll take a look on it and help.

jmini commented 6 years ago

I have continued to work on my jaxrs feature branch https://github.com/jmini/swagger-codegen-generators/tree/jaxrs

The result is a pull request for the swagger-codegen-generators repository: https://github.com/swagger-api/swagger-codegen-generators/pull/29

It provides a first version for following languages:

Feedback is appreciated.

jmini commented 6 years ago

@asnowfix:

I am trying to generate server-side code out of a open api 3.0 specification. I tried the 2 backends that seems to be available in 3.0.0-rc0 (jaxrs & nodejs-server),

I think that the languages that are not available should not appear in the list. I have proposed pull request #7749 to remove them.

jmini commented 6 years ago

The jaxrs generators are now available in the 3.0.0-SNAPSHOT version. This is an initial version, feedback is welcomed. I have already seen some errors with some configurations on the continuous integration server.

I guess that this issue can be closed.