Generate Swagger specification from Java source code

[David Blickstein]

I have to think this question may have been asked here before.  But I couldn't find a way to search the forum, and though I've seen the same question asked in other forums, I've yet to see an answer.

What I want to do is described very simply:  I'm looking for a tool that generates a Swagger specification file from  JAX-RS annotated Java source code.

A key element is that it works off the source code, not off a deployment.

Does such a tool exist?  Or is there some sort of method by which I can accomplish this?

Thanks

[Ron Ratovsky]

Sure, take a look at https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[David Blickstein]

Ron, I appreciate your response, but I don't think that page provides a method to do what I need to do.

That page is just a page on how to introduce Swagger into a web application.   What I'm looking to do is have a way to generate a Swagger specification file WITHOUT having to do that.

I have found a github project that may accomplish that by providing a Javadoc doclet that writes out a Swagger specification instead of Javadoc documentation:

         https://github.com/conorroche/swagger-doclet

But I'd be interested to know of any other solutions.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Ron Ratovsky]

You will never be able to generate a good API definition from code without adding more to it.

The reason is simple – the descriptions are just not there.

 

You can actually use swagger-core to generate something without adding any annotations to your code.

That would still be lacking of descriptions and you can add that manually later.

If you want it to work at build time and not deployment time, you can look at the maven plugin - https://github.com/kongchen/swagger-maven-plugin.

For that you’d still want to add the annotations, but you won’t need to expose it at runtime.

We are not affiliated with that plugin, so won’t be able to provide support, but it should be good.

 

The other option is to not generate it from the code but use something like http://editor.swagger.io to manually write your API description.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[David Blickstein]

Ron, 

Again thanks.  Let me explain what I'm doing and what my immediate and subsequent goals are.

We have a fairly large collection of APIs and endpoints in JAX-RS.    These are all in one fairly large and somewhat monolithic project.   The project, having been around for awhile, uses Ant (without Ivy) rather than Maven.

We are trying to produce a number of client SDKs that provider wrappers for the REST services.   As we don't know what platforms our partners/customers will ask for, we are hoping to use swagger-codegen to "easy" the generation of such wrappers for any new platforms we have to support.

My immediate goals are:

• Generate a Swagger Specification from the code
• Use Swagger Codegen to generate skeletal wrapper templates for one or two platforms
• Merely "have something to show" in the way of API documentation.    At this point, it need NOT have much detail other than what is available via the JAX-RS annotations.   

A key point here is that this first stage is merely a "demonstration" or POC.   Another key point is that we want to minimize the "pain" of having to manually update many client SDKs (and documentation) whenever the core REST API is changed.    

Now the longterm goals are:

• Fully annotates the endpoints (beyond merely what JAX-RS provides) with Swagger annotations
• Generate a Swagger Specification from that as part of the build
• And generate from that:
• Those same skelete templates (perhaps for multiple client platforms)
• Excellent API documentation
• And my hope is that we would not have to check what most of what Swagger-codegen generates but have additional code that connects the wrappers to the actual API servers.    Having reviewed what Swagger-codegen generates for Java, I see that the code is generated in a way such that the templates and their implementations can be done in separate files (the former generated by the built, the latter checked into source control)

Question:  Does this strike you as a feasible approach

The challenges I seem to be facing stem from the fact that I want to generate a specification file a) as part of the build and b) in a non-Maven project and thus I can't use the Maven plugin.    That's why I'm trying to use swagger-doclet.     

I'm greatly appreciative of your efforts to help me.

            dave

[Ron Ratovsky]

Hi David,

 

The short answer is – yes, you can do all that.

 

The longer version is slightly more complicated.

I’m not familiar with swagger-doclet – not with its quality, maintenance level, or even what version of the spec it produces (which is critical).

The use of Ant does pose challenges, however, as far as I know, you can run maven plugins from an Ant build.

Given the maturity of the tools, I really think that would be the best approach for you to explore.

 

 

 

From: <swagger-sw...@googlegroups.com> on behalf of David Blickstein <dab...@gmail.com>
Reply-To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Date: Friday, 23 June 2017 at 11:21
To: Swagger <swagger-sw...@googlegroups.com>
Subject: Re: Generate Swagger specification from Java source code

 

Ron, 

--

[David Blickstein]

I completely agree that I am more likely to be successful running the Maven plugin from Ant than running Javadoc with the swagger-doclet from Anti.   To wit, so far the latter has had some problems, particularly in the area of classpath, which I think would be avoided with the Maven plugin which, as you say, seems a more mature/active effort.

Thanks again,

           Dave

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Phil]

Hi David,

Have you found a good solution yet? I am also looking for exactly the same. I was thinking that there is an equivalent to java doc where I can create the doc offline when I need it. 

Phil

[David Blickstein]

Phil,

I haven't yet made any solution work, but I am hopeful about one approach I'm taking and when/if I get it to work, I'll post about it.

The approach that I'm most optimistic about is to use the Swagger Maven Plugin.     Our project being Ant-based, I don't have a POM file.    And I don't want to try and create a POM file that duplicates all the dependencies as that would be non-DRY.     However, I have seen some articles about how to tell Maven to use a directory of jars (such as "/lib" in he project) as if it were a sorta Maven repository.   This is not quite the same as a Maven "internal repository", and i's of course not a "recommended practice".  But being as here's no really good way to do this, the "least bad" way seems reasonable.

Another approach you can try is that there is a git hub project for a Swagger Javadoc doclet.    I don't think that project has the same traction/community-endorsement that the Maven plugin has, but the classpath/dependency problem there is might be easier to solve.    I abandoned that approach because of the lower level of traction, but also because my project uses jibx, which introduces a sort of "pre-compile" dependency that produces .class files prior to the main "compile" portion of the build.

Like I said, I'll post when I get something to work.

            db