I am attempting to expose documentation (like Javadocs) for a SOAP Service. Best case, it would either be exposed directly from the WSDL or through an autonomously generated report. I am using CXF as my SOAP implementation.
I have tried using the WSDL Viewer found here, but I havn't found a good tutorial on how to annotate my methods to get the structure and level of detail seen in his example.
The best solution that I’ve found thus far is to use an engine known as Enunciate (http://enunciate.codehaus.org/). Once added to the project it reads the JavaDocs and composes a set of HTML files. I don't fully understand all of the features or problems (it generates and links to its own WSDL, which isn't ideal, and does "scratch work" within an extra folder in the project which then reads as an error unless deleted), but it does successfully read and expose the JavaDocs in a clear and useable manner.
Related
I am trying to incorporate swagger-codegen in my new greenfield project, using Java (jaxrs-jersey2).
There are a lot of resources out there already documenting various parts of the project; however, I still haven't been able to find out any high-level advice on the best workflow to use with these tools.
As I understand it, swagger-codegen will be able to generate client-side code to interact with my API, such that I don't have to write this myself. This will happen by looking at a swagger.yaml (2.0) or openapi.yaml (3.0) file. This part is clear.
However, there seems to be multiple ways of generating this specification file. As I understand it, there are two primary ways:
Write a server implementation using a combination of jaxrs and Swagger annotations - have a maven plugin run as part of the compile step, generating a swagger.yaml specification file to be used by the client-generation plugin.
Write a swagger.yaml specification first, and generate server-stub code for Jersey, implementing only business logic, separate from all server boilerplate.
Which of these two ways is the recommended workflow? It sounds like (2) means writing less code and focusing on just application logic, without worrying too much about Jersey-specific glue to make the API work. This also means that the single source of truth for the API becomes a simple yaml file, rather than a bunch of Jersey code.
However, I'm unsure how to properly set this up:
Does my build need to have a compilation phase where server stubs are constantly regenerated?
Do I simply extend from the generated server stub and never worry about annotating API paths with #Path, #GET, etc?
Am I misunderstanding the use-case for server-stub generation? I.e. is the first approach (Jersey code-first) more appropriate?
If there is no real difference between the two approaches, when would you pick (1) over (2) and vice-versa?
Many thanks.
I am working on a rather large API (390+ functions) and I am trying to pull together all the information that the documentation team would need in order to create docs for the project.
I have decided to use JSON Hyperschema to represent this.
I created an annotation processor to look for all of the javax.ws.rs.Path annotation from my code and grab the Javadoc, http method (from annotation) and other parameter information but I am running into a problem.
Hyper schema recommends, and my project spec requires, that the objects sent across an API are to be included as schema in the hyper schema. Typically I would use Jackson to accomplish this. However, as I am in an annotation processor that is not in the main API project, I cannot use class references (ex. User.class where user is an object in my API project and not in my processor) without generating errors. (This is explained here).
My question is, what is the best way around this limitation? I have come up with one way, explained below, but I want this to be pluggable into any other service (of the same format) to document them as well.
As a solution to this, I have thought to break my generator across compile time and runtime. At compile time I would generate JSON hyperschema with placeholders to reference the object schemas. It would also generate a resource file with full names of all of the objects.
At runtime I was planning on generating the schemas for the returned objects then inserting the links to them into the JSON.
IMHO this solution doesn't seem very "elegant". Does anyone have any insight into other ways to accomplish this?
I would recommend following projects:-
jsonschema-hypermedia-support which confirms to enter link description here
OR
Use Spring HATEOAS
Also see
this stackoveflow thread about Restful API
At work, we currently have a WSDL interface as well as a semi-RESTful interface that we're looking to expand upon and take it to the next level.
The main application runs using Servlets + JSPs as well as Spring.
The idea is that the REST and WSDL are interfaces for an API that will be designed. These (and potentially other things in future) are simply a method through which clients will be able to integrate with the interface.
I'm wondering if there are any suggestions or recommendations on frameworks / methodologies, etc for implementing that under-lying API or does it make sense simply to create some Spring beans which is called either by WSDL or REST?
Hope that makes sense.
Have a look at Eunicate it is great . You are using spring , Spring has had support of SOAP for a while and Spring 3 has support of REST (Creating and Consuming).
Your approach makes sense. Probably the most important advice is to make the external API layer as thin as possible. You can use Axis, Apache CXF, Jersey, etc. to handle the implementation of the REST or SOAP protocols, but the implementation of those services should just load the passed in data into a common request object, and pass that into a separate service that handles the request and returns a response object which the external API layer will marshall into the correct format for you.
This approach works especially well when you have a competitor providing similar services and you want to make it easy for their customers to switch. You just build a new external API that mirrors the competitors, and simply translates their format to your internal api model and provided your services are functionally equivalent, you're done.
This is a really late response, but I have a different view on this topic. The traditional way as we know it is to unmarshall xml to java and marshall java to xml. However if the wsdl changes then it would effectively be a structural change in the code which would again require a deployment.
Instead of the above approach if we list the fields mentioned in the wsdl in a presistent store, load the mappings in memory and prepare our structures based on these mappings we would have to have many less changes for this..Thus IMO instead of using existing libraries a configurable approach to unmarshalling and marshalling should be taken.
I'm looking for a solution of dynamic web service client such as DII from JAX-RPC.
I need to generate a client from a WSDL.
But the WSDL is only known at runtime (so I don't have any available interface).
I had a look on JbossESB, JbossWS, JaxWS,JaxRPC, but I could'nt find anything that fits this requirements.
Thanks for your help.
It appears that this is possible with CXF and some java reflection.
jax-ws-dynamic-dispatch-with-cxf
I'm personally looking for a solution for this + a dynamic server model as well.
Good luck.
finding a ready-made solution to your problem is not easy. at least none exist AFAIK. due to the inherent, unknown complexity of the backing schema types associated w/ an operation's request and response, it's not possible to have such a solution.
however, putting together the correct tools, or using some open-source frameworks/libraries/tools you might be able to achieve something similar. basically you'll need to have a WSDL4J implementation, along with a schema parser like XMLBeans to get this working.
A tool which comes to my mind is SoapUI. it achieves something similar - user loads a WSDL at runtime and thereafter can execute operations. the source of this tool is also available for modification under LGPL here. you'll need to strip and salvage the core functionality that suits your need. or best, build one of your own :]
I use XFire to create a webservice wrapper around my application. XFire provides the webservice interface and WSDL at runtime (or creates them at compile time, don't know exactly).
Many of our customers don't know webservices very well and additionally they simply don't read any external documentation like Javadoc. I know that it's possible to add documentation (for parameters and methods) directly to the WSDL file.
I thought about Annotations or Aegis XML files but I don't know how... Do you know a way?
Edit: I just found this JIRA issue but the last activity was 2006. Any ideas?
XFire is slowly headed for /dev/null. Use CXF instead. In other words, XFire is being deprecated in favor of CXF - it's pretty much the same developers.
Since you use the Java-first approach, I suggest you generate you WSDL once and for all with CXF's java2wsdl tool, then you put your documentation in that and tell CXF to use that documented WSDL instead of letting CXF generate its own (undocumented) WSDL at runtime/deploy-time.
This page has pretty much everything you need to know about creating a web service in CXF.
And my last hint regarding CXF - use Aegis for data binding instead of JAXB. It doesn't work for complex POJO.
In my experience we have no problem with complex POJO and JAXB, the only problem is that the code starts to be cluttered with JAXBElements. On the other hand, Aegis documentation is pretty sparse and not well-maintained with relation to CXF.
Let's me add my two cents regarding XFire. We had very serious issue with XFie under JDK6 (both Tomcat 6.0 and 5.5).Please take a glance at that issue. In our case XFire with 4+ web services under JDK6 leads to hanging application servers (thread deadlocks etc.). It's interesting, but under JDK5 everything was OK.
And I completely agree with Christian Vest regarding migration to CXF from XFire. It has sense in many cases e.g. ESB Mule 2 doesn't support native XFire connectors anymore (see also).
And I wish to add that migration from XFire to CXF is not straitforward way (e.g. CXF has jar dependences that conflict with some hibernate releases see also), but it's doable. In our case we did it for couple days without code correction (Spring only configuration).
And my last hint regarding CXF - use Aegis for data binding instead of JAXB. It doesn't work for complex POJO.