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
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'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
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'm currently developing a software where the user can define a complex hierarchy of objects as settings.
Also this settings objects will provide interfaces as an API for other developers.
Now I want to store these setting and reload it.
I'm currently considering different ways to do exactly that, but none of my solutions are "good" in my opinion.
The main goals should be:
It should output a String, because i prefer a human readable configuration over a fast one.
It should be reliable even when the the code is changing. This means not it should do magic, but it should be obvious that an change could break already stored configuration. (Eg. How do I prevent that my colleague renaming a class and breaking production. )
Storing and loading should work with object, interfaces and generics.
Keep configuration of what is stored how as low as possible. I would prefer convention over configuration.
I know many of you faced the same or a similar issue while developing.
So what was your solution? Which framework did you use and why?
All solutions I came up with are either not reliant, a huge configuration or to much code.
So I'm looking forward to get some good new perspectives on this topic from all of you.
Thanks.
I would recommend XStream. Without any configuration it has similar capabilities as java.io.*ObjectStream but outputs XML instead of binary blob. You will only want to add few aliases for class names to make file more readable.
I recommend to specify a XSD and use JAXB to generate the Java classes and marshal and unmarshal XML based settings files.
Make sure the root tag contains the version of the XSD. You can use StAX to read the version first and determine the correct version of JAXB classes if you need to support several versions.
For further information this how i solved this problem now:
I used Gson for serializing the object hierarchy to JSON. Added an Generic TypeAdapter to it for serializing and deserializing all known Interfaces. This adapter saves the class name into the JSON object and constructs this class while deserializing. No additional configuration is needed, besides registering this TypeAdapter for each used Interface.
In order to make it reliable I will add an Unit Test to the project that will deserialize the complete possible configuration. So any changes to the code will break the tests.
In this way i can fulfill all of the points mentioned above.
I hope this helps anyone.
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.