I'm trying to generate swagger documentation for a Vert.X Reactive application. The current solution is a static YAML file that is converted to an openapi.json file.
This is an awful lot of work and I'm wondering if there is a way to do this automated. I know there are solutions to do it the other way around, but because it is an existing application this is not a possibility.
I found the following library: https://github.com/outofcoffee/vertx-oas Which is kind of the direction I want to go but sadly isn't up to date.
I expect it to be possible but I'm a little bit stuck right now.
vertx-web-api-contract mantainer here. Unfortunately, we have no official solution for Vert.x Web to OpenAPI conversion because of the design of Vert.x Web Router APIs.
Starting from the Router there is no way to infer what are the request parameters, their location in the request, their schema, if they are required or not, their style, etc. The same thing applies for response bodies where you can't infer the body schema.
Jax-rs and similar technologies allow this conversion because they describe the request contract using some declarative API (e.g. annotations), so a converter just needs to read this description to translate it to the OpenAPI contract
Francesco
Related
I'm working within IBM Integration Bus and I found myslef in need of validation of the messages that I recive. Since IIB does not support any kind of validation in this regard, I was wondering if there are any external libraries that could validate those messages for me.
So far, I found this https://github.com/swagger-api/swagger-inflector/blob/master/README.md#payload-validation But I was wondering if there are alternatives that might fit my needs a little better.
Thanks for any suggestions.
One option is the swagger-request-validator. It lets you validate requests/responses against a Swagger / OpenAPI definition.
There are modules available for integrating with WireMock, Rest Assured, Pact etc., or you can use the validator directly.
Take a look at the example usages for code samples on how to use it.
I came across the below link in which JSON equivelent XML modeling was used to enable graphical mapping of a JSON message here.
In the same manner, you can create an equivelent XML model and switch from JSON to XML domain then run validation using ResetContentDescriptor node. But, I am not sure about the performance. If were you, I would test and compare this solution to yours.
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.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.
From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.
The kind of things which need to be documented for each endpoint are:
Service Name
Category
URI
Parameter
Parameter Types
Response Types
Response Type Schema (XSD)
Sample requests and responses
Request type (Get/Put/Post/Delete)
Description
Error codes which may be returned
And then of course there are some general things which are global such as
Security
Overview of REST
Error handling
Etc
These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it.
I've thought of maybe using annotations, and writing a small program which generates XML, and then an XSLT which should generate the actual documentation in HTML. Does it make more sense to use custom XDoclet?
Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.
Integration guide: https://github.com/swagger-api/swagger-core/wiki
More Information: http://swagger.io/
Unfortunately, Darrel's answer is technically correct, but is hocus-pocus in the real world. It's based on the ideal that only some agree on and even if you were very careful about it, the chances are that for some reason outside your control, you can't conform exactly.
Even if you could, other developers that might have to use your API may not care or know the details of RESTful patterns... Remember that the point of creating the API is to make it easy for others to use it and good documentation is a must.
Achim's point about the WADL is good however. Because it exists, we should be able to create a basic tool for generating documentation of the API.
Some folks have taken this route, and an XSL stylesheet has been developed to do the transform:
https://wadl.dev.java.net/
Although i'm not sure it will totally fit your needs, take a look at enunciate. It seems like a good documentation generator for various web-services architectures.
EDIT Enunciate is available under github umbrella
you might be interested in Jersey's ability to provide so called WADL description for all published resources in XML format at runtime (generated automatically from annotations). This should be containing already what you need for basic documentation. Further you might be able to add additional JavaDoc, though that requires more configuration.
Please look here:
https://jersey.java.net/documentation/latest/wadl.html
Darrel's answer is exactly right. The kind of description must not be given to clients of a REST API because it will lead the client developer to couple the implementation of the client to the current implementation of the service. This is what REST's hypermedia constraint aims to avoid.
You might still develop an API that is described that way, but you should be aware that the resulting system will not implement the REST architectural style and will therefore not have the properties (esp. evolvability) guaranteed by REST.
Your interface might still be a better solution than RPC for example. But be aware what it is that you are building.
Jan
You might find rest-tool useful.
It follows language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs.
You can use it only for documenting your APIs, but this specification can immediately be used to quality assure the implementation of the real services.
If your services are not fully implemented yet, but for example should be used by a web frontend application, rest-tool provides instant mocking based on the service description. content schema validation (JSON schema) also can be easily added beside the documentation as well as used by the unit tests.
I hate to be the bearer of bad news, but if you feel the need to document the things you listed, then you probably did not create a REST interface.
REST interfaces are documented by identifying a single root URL and then by describing the media type of the representation that is returned from that URL and all the media types that can be accessed via links in that representation.
What media types are you using?
Also, put a link to RFC2616 in your docs. That should explain to any consumer how to interact with your service.
What is a good way to render data produced by a Java process in the browser?
I've made extensive use of JSP and the various associated frameworks (JSTL, Struts, Tapestry, etc), as well as more comprehensive frameworks not related to JSP (GWT, OpenLaszlo). None of the solutions have ever been entirely satisfactory - in most cases the framework is too constrained or too complex for my needs, while others would require extensive refactoring of existing code. Additionally, most frameworks seem to have performance problems.
Currently I'm leaning towards the solution of exposing my java data via a simple servlet that returns JSON, and then rendering the data using PHP or Ruby. This has the added benefit of instantly exposing my service as a web service as well, but I'm wondering if I'm reinventing the wheel here.
I personally use Tapestry 5 for creating webpages with Java, but I agree that it can sometimes be a bit overkill. I would look into using JAX-RS (java.net project, jsr311) it is pretty simple to use, it supports marshalling and unmarshalling objects to/from XML out of the box. It is possible to extend it to support JSON via Jettison.
There are two implementations that I have tried:
Jersey - the reference implementation for JAX-RS.
Resteasy - the implementation I prefer, good support for marshalling and unmarshalling a wide-range of formats. Also pretty stable and has more features that Jersey.
Take a look at the following code to get a feeling for what JAX-RS can do for you:
#Path("/")
class TestClass {
#GET
#Path("text")
#Produces("text/plain")
String getText() {
return "String value";
}
}
This tiny class will expose itself at the root of the server (#Path on the class), then expose the getText() method at the URI /text and allow access to it via HTTP GET. The #Produces annotation tells the JAX-RS framework to attempt to turn the result of the method into plain text.
The easiest way to learn about what is possible with JAX-RS is to read the specification.
We're using Stripes. It gives you more structure than straight servlets, but it lets you control your urls through a #UrlBinding annotation. We use it to stream xml and json back to the browser for ajax stuff.
You could easily consume it with another technology if you wanted to go that route, but you may actually enjoy developing with stripes.
Check out Restlet for a good framework for exposing your domain model as REST services (including JSON and trivial XML output).
For rendering your info, maybe you can use GWT on the client side and consume your data services? If GWT doesn't float your boat, then maybe JQuery would?
Perhaps you could generate the data as XML and render it using XSLT?
I'm not sure PHP or Ruby are the answer if Java isn't fast enough for you!