I am building a rest api and part of the requirement is that we write documentation according to the open api specification. I am using (http://editor.swagger.io) to do this, and I find it irritating, and way less affective than creating normal javadoc. Is there a maven plugin, or something that can build documentation from comments in .yaml or .json format according to the open api specification? Thanks!
Seems like you're looking for that maven library https://springfox.github.io/springfox/docs/current/
It can automatically generate specifications in html
Related
I am looking at generating some API documentation, hopefully using Swagger, in a few different projects of mine. Having never used Swagger, I am trying to find a very simple solution to generating HTML documents via Maven.
The underlying REST framework being used in these projects is Jersey. I found documentation from Swagger but it doesn't seem to have any examples of simply producing HTML files. Most of their examples seem to embed the API documentation into the actual service itself.
So my questions are:
How can I generate HTML documentation with Swagger via Maven?
Is attaching the documentation along with the service normal to do with REST applications?
You will need to use swagger-codegen to generate an HTML.
https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation
To generate the HTML doc with swagger-codegen, you will first need to generate an OpenAPI documentation. Since you are already using Jersey as your REST framework, it is probably the easiest to pull in swagger as a dependency into your project and annotate all your API servlets. Doing so, will tell swagger to read all your code and generate an OpenAPI spec. You can follow the steps in https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration to get started.
Good luck!
I'm writing documentation for my java file. In that documentation, I want to add some html links at the end of each generated file. For that, what I have to use while writing java documentation?
If you are using Eclipse as IDE, you can use the plugin JAutodoc:
http://jautodoc.sourceforge.net/
To add a default text at the beggining of each text file.
According to the javadoc manual (can't find a newer version right now), you should use -footer when you generate your java API documentation from the CLI, for instance:
javadoc -footer "<b>Copyright 2015 Lakshmi Prasanna</b><br>" com.mypackage
Here's a similar example, but that uses -header instead.
Now, if you use a good IDE, at the very least it should allow you to type that somewhere in the project settings. Back in the day Eclipse wasn't very flexible, so I had to make an Ant script (yuck).
EDIT:
One limitation with this approach is that the CLI -options depend on the tool. This works with the standard javadoc command but might not work with another vendor's doclet. However I'm not sure there's a universal way to achieve what the OP asked.
Anyway, it seems to be: NOT -footer but -bottom.
I am trying to generate swagger documentation, for that I need to start the server. I Want to generate swagger documentation offline (with out starting the server), I just got this link swagger-codegen-maven-plugin
But when I added above plugin to POM.xml (Suppose to generate HTML doc during maven build i feel), it is not at all doing anything. Please help.
Take a look at this plugin:
https://github.com/teamcarma/swagger-jaxrs-doclet
As the JSON resource listing is generated offline from source code it means that you do not need to add any runtime dependencies to your project and avoid potential headaches with different jar versions and jaxrs implementations. This also avoids increasing the size of your artifacts
To generate the HTML documentation, you need to set the value of the language tag in the configuration to HTML. In the example from your link, it is set to java. Change it to html. If you need both Java and HTML to be generated, have two execution blocks, one for Java, one for HTML.
I'm getting this error trying to Compile my GWT Project:
No source code is available for type org.scribe.oauth.OAuthService; did you forget to inherit a required module?
I have included the scribe .jar file in my "war/WEB-INF/lib", and imported it. Maybe I have to add it to the app_name.gwt.xml? I have tried to do it, but Scribe does not contains any .gwt.xml file.
In GWT you are restricted to use only some of the java classes since it is not possible to convert all the java classes to javascript. You can find a list of the allowed classes in this link: List of Classes
And it is not possible use classes related to Threads,IO,Network, etc...because of the compatabilty.
I use Scribe with no problems. But it's a server-side library. You should have no references to it in your GWT code.
You have to have the Java source code for Scribe in order for the GWT compiler to compile it (translate it into javascript). If it is available then you can add it to your source tree and and specify that it is "inherited" in the gwt.xml document.
Of course, check with Google's GWT forum for any updates. I know they are working on a better solution to this problem.
I just checked and Google has OAuth available as an extension to GWT. That is your best solution. Look here:
code.google.com/p/gwt-oauth2/
I tried to use CEDET to get auto completion in Emacs and that works fine for C/C++. But I cannot find anything about how to use CEDET with Java without the help of JDEE, which is thought out of date and not compatible to CEDET 1.1. I got a tags file using utility found here but I don't know how to integrate that into CEDET system. According to CEDET's website, that's possible. But they don't explain how to do it. Is there someone willing to answer this question?
Here is some sample of the tags file generated by that utility:
java.applet.Applet$AccessibleApplet
protected java.applet.Applet$AccessibleApplet(java.applet.Applet)
public java.applet.Applet$AccessibleApplet.getAccessibleRole() returns javax.accessibility.AccessibleRole
public java.applet.Applet$AccessibleApplet.getAccessibleStateSet() returns javax.accessibility.AccessibleStateSet
It is possible to have CEDET pull in tags from a .jar file. It works by using javap to extract the tags in text form, and then it parses that data.
It isn't very easy to set up since in CEDET, the concept of where to find your library files is part of EDE, the project management system, not the parser and smart completion system. The only Java based project supported in CEDET 1.1 is Android.
The basics is to first enable the javap database by loading it with (require 'semanticdb-javap) in CEDET 1.1, or (require 'semantic/db-javap) in the bzr version of CEDET.
Once you've done that, you can configure it via the cedet-java-classpath-extension. I'm a little fuzzy on the details of what happens next, but folks have reported success on the mailing list.
If you use CEDET from the bzr repository, there is the ede-java-root project, which is similar to the ede-cpp-root project. That project type lets you configure what your library path is. The doc for that is in the ede/java-root.el file with the project type, and shows you the basics of how to use it.