Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I have some RESTful APIs on Jersey 2.17 with Jackson.
They are all on JSON style, and work very well.
But I want to generate a good RESTful Docs withJSON sample for developers.
So I tried some maven plugins,
Firstly I tried ServiceDocGen Maven Plugin,
it directly generate HTML docs with Json sample.
But it doesn’t know Jackson annotation like #JsonProperty, #JsonIgnore,
So the JSON sample is inaccurate.
Then I tried swagger-jaxrs-maven, it knows some Jackson annotation like #JsonProperty, but still can't handle #JsonIgnore. Also it is the description of the data schema, not the sample. It will fail if the API directly return a JSON string.
I also tried jaxrs-raml-maven-plugin, it can only use JAXB to generate sample which is inaccurate.
Basically My requirement is simple:
Generate endpoint URL and parameter description from JAX-RS annotation, every plugins I tried did it very well.
Generate sample JSON on payload, I don't care JSON sample data logic is correct or not, I care if the data structure is accurate. So setting fixed data on certain type is OK, like ServiceDocGen always set "text" on a string.
I believe it is not so tough to generate JSON sample: Firstly go through Java Object tree, fill in random type safe data. Then call Jackson deserializer to generate json data.
But until now I can't find any maven plugin is doing this job well.
Any suggestion ?
You can try spring-restdocs:
https://github.com/spring-projects/spring-restdocs
http://docs.spring.io/spring-restdocs/docs/current/reference/html5/
It generates documentation snippets based on tests of your endpoints (via RestAssured or MockMvc). This way you have a programmatic link between your code and your documentation.
I dont think you will find a tool out there that does exactly that.
Your best bet is to write a swagger.json file and import the swagger-ui webjar dependency.
<dependency>
<groupId>org.webjars</groupId>
<artifactId>swagger-ui</artifactId>
<version>${swagger-ui.version}</version>
</dependency>
You can then customize/override the index page of swagger-ui and hard code it to point to the localhost path to your swagger.json file or wherever you want.
If time is not a constraint, you could then write a maven plugin to scan and reverse engineer your JAX-RS annotations using reflection to generate a swagger json file. Personally, I prefer to maintain only a single json file and generate my API and models from that file.
I'd echo cosbor11's direction, Swagger is the way to go if you want to keep code and readable docs in sync. Check out Swagger Inflector which supports a service-first approach as described by Phil Hauer: https://blog.philipphauer.de/enriching-restful-services-swagger/
With Inflector, you can either start with API spec to generate stubs and proxies, or you can start service-first where your code annotations (see below) generates the Swagger spec for you:
#Api(value = "customers", description = "RESTful API to interact with customer resources.")
#Path("customers")
public class CustomerResource {
#ApiOperation(value = "Get all customers", notes = "Get all customers matching the given search string.", responseContainer = "List", response = Customer.class)
#GET
#Path("/")
#Produces(MediaType.APPLICATION_JSON)
public List<Customer> getCustomers(
#ApiParam(value = "The search string is used to find customer by their name. Not case sensetive.", required = false, defaultValue = "") #QueryParam("search") String searchString,
#ApiParam(value = "Limits the size of the result set", required = false, defaultValue = "50") #QueryParam("limit") int limit) {
List<Customer> customers = dao.getCustomers(searchString, limit);
return customers;
}
}
Once you live in Swagger/OpenAPISpec land, there are a ton of tools (beyond swagger-ui) that help you generate static docs, interactive samples, and use whatever level of metadata/defaults that are in your Swagger spec to produce usable, human-readable examples.
https://github.com/sourcey/spectacle
https://lucybot.com/
https://swaggerhub.com/
If you have problems implementing Inflector, definitely reach out to #olensmar on Twitter who works directly with #fehguy on the Swagger spec and tooling.
I finally finished my task by creating my own Java object creator.
To help other people who has the same issue, I added this project into GitHub:
ObjectTreeCreator
After this project, the remaining tasks are simple:
find all API methods by Java reflection
find return class type on every API method by Java reflection
call ObjectTreeCreator to generate an object from the class type
call Jackson ObjectMapper.writeValueAsString to generate Json string from this object
Now my RESTful doc generator works very well. it only needs about 10 seconds to generate html document for about 300 RESTful APIs.
I also added into my maven build process. So every time my build server automatically find all APIs and generate RESTful doc for me.
The generated JSON structure is exact the same as real API response.
By the way I also used Integration testing result if it exists.
ObjectTreeCreator is only used when Integration testing doesn't exist.
Related
I've been using arrow-kt and spring together a lot lately. I've actually constructed a bridge between the two with several key features, one of which is a spring controller that returns an Either will automatically unwrap it and either handle the exception (Left) or return the result (Right). My long term goal is to publish this as a library.
My latest obstacle is Swagger, or more accurately springdoc openapi. Obviously it is seeing the Either, but i want it to show only the Right value as the success response type. While I know there are annotations where I can set the response model on each controller method individually, I'm trying to avoid this.
My real goal is to setup some global converter so that wherever Swagger sees an Either it will automatically unpack this. I'm just not super familiar with the customization API in Spring doc, and everything I Google just points me to the ApiResponse annotation solution.
How can I define default handling for this type of response?
Ok, this is my Nth question regarding this topic, and I'm getting really frustrated with Grails. Please have a quick look on one of my earlier questions for more details.
Among other things, my problem is that sending JSON formatted data to the controller when testing doesn't seem to work. The controller doesn't get null object, but the argument passed is practically empty--the JSON properties don't get set.
Aside from the controller code from the link above, I also tried,
def save() {
def model = new MyModel(request.JSON)
model.save()
}
but it still fails to set properties.
From my Web searches, I read that in older versions, parseRequest must be set to true in UrlMapping.groovy so that request data formatted in XML, JSON, etc. would automatically be parsed and passed as controller method argument. I'm working on Grails 2.3.9, and I'm not sure if it's still necessary to do that.
The time I thought I'd save if I use Grails on this project is being spent on looking for an answer to this seemingly simple task of testing a RESTful Web service.
No since 2.3.0 the parseRequest option doesn't do anything. The request is parsed lazily only when request.XML or request.JSON is accessed or when binding to a command object.
An automated system is going to feed the application[Play with Scala] with JSON's and the contract of the integration is that there would be no validation required on JSON's since it will be always deemed right. But for testing purposes when we seed the data more often than not we are not able to send the correct JSONs. We would like to validate the JSON's we receive based on a set of grammars. Is there a library that already does this. Or is there a better way to do this?
Example: Grammar for valid Json :
"header"->[String, mandatory],
"footer"->[String],
"someArray"->Array[String, mandatory],
"someArrayObject"->Array[
{
{"key1"->Int, mandatory},
{"key2"->String}
},
mandatory
]
and passing,
{
"header":"headerContent",
"footer":"footerContent",
"someArray":["str1", "str2"],
"someArrayObject"->[
{"key1":4, "key2":"someStringValue"},
{"key1":5, "key2":"someOtherStringValue"}
]
} // would pass
{
"header":"headerContent",
"footer":"footerContent",
"someArray":["str1", "str2"]
} // would notpass since someArrayObject though declared mandatory is not provided in the sample json
I think play-json will satisfy you play-json
In play-json you don't create a validator as it is, but a json transformer which is a validator in itself. The author of the framework wrote a series of blog-posts to show how to work with it: json-transformers
* Haven't noticed you use play) Play has play-json included by default.
You don't have to roll out your own DSLs. This is why we have schemas. Just like using XML schemas to validate your XML docs, you can define a JSON schema to validate your JSON objects. I had a similar requirement when building a RESTful web service using Play. I solved it by using the JSON Schema Validator library.
I have used the JSON Schema draft v3. The library supports draft v3 and draft v4. You can validate your schemas against possible JSON inputs using a web application that uses the same library. The web app is hosted here.
Also there are pretty nice examples that use the draft v4. You can check them out from here.
In Play 2, I have composed an action that takes the schema resource file name as input. This keeps away a lot of JSON validation code from the controller action itself.
#JsonValidate("user-register.json")
public static Result create() {
...
}
This way, all JSON Validation code stays in one place. Pretty neat :)
I am developing an application system that has multiple executable applications on different platforms (java and .net).
For communication between them I am using JSON format. So I need to map object to and from json very frequently. Current solution (seems workaround) is jackson at java end and Newtonsoft.Json at .NET end. Problem is property name are not same and not all properties will be required at de-serialization end
So my questions are:
1. Is there any mapper to do this.
Currently using NewtonSoft.JSON.DatasetMapper at .Net end and
jsonanysetter annotation at java, but in this approach mapping
definition is loaded for each object as actual object mapping code
is in code. For example:
//C#
myobj.prop1 = dataSet.Tables[0].Rows[0]["propertyName1"].ToString();
// and so on.....
//Java
switch(key)
{
case "prop1":
myobj.setPropery1(value.toString());
break;
//and so on......
}
2. Object transformationRate needs to be very high as object are
sent and recieved at very high speed. say some 10k objects per second.
We used GSON in one of our project , i think this reference may help you, Apart from it ,there is a similar question may help you. another q/a in stackoverflow
You should take a look at Jackson. It's the de facto JSON library for Java and will happily handle turning objects into JSON and back again. It has many options to allow you to alter the output, and most per-object configuration is carried out using annotations so is visible in your model rather than hidden away in a separate configuration file.
I'm developing a RESTful interface which is used to provide JSON data for a JavaScript application.
On the server side I use Grails 1.3.7 and use GORM Domain Objects for persistence. I implemented a custom JSON Marshaller to support marshalling the nested domain objects
Here are sample domain objects:
class SampleDomain {
static mapping = { nest2 cascade: 'all' }
String someString
SampleDomainNested nest2
}
and
class SampleDomainNested {
String someField
}
The SampleDomain resource is published under the URL /rs/sample/ so /rs/sample/1 points to the SampleDomain object with ID 1
When I render the resource using my custom json marshaller (GET on /rs/sample/1), I get the following data:
{
"someString" : "somevalue1",
"nest2" : {
"someField" : "someothervalue"
}
}
which is exactly what I want.
Now comes the problem: I try to send the same data to the resource /rs/sample/1 via PUT.
To bind the json data to the Domain Object, the controller handling the request calls def domain = SampleDomain.get(id) and domain.properties = data where data is the unmarshalled object.
The binding for the "someString" field is working just fine, but the nested object is not populated using the nested data so I get an error that the property "nest2" is null, which is not allowed.
I already tried implementing a custom PropertyEditorSupport as well as a StructuredPropertyEditor and register the editor for the class.
Strangely, the editor only gets called when I supply non-nested values. So when I send the following to the server via PUT (which doesn't make any sense ;) )
{
"someString" : "somevalue1",
"nest2" : "test"
}
at least the property editor gets called.
I looked at the code of the GrailsDataBinder. I found out that setting properties of an association seems to work by specifying the path of the association instead of providing a map, so the following works as well:
{
"someString" : "somevalue1",
"nest2.somefield" : "someothervalue"
}
but this doesn't help me since I don't want to implement a custom JavaScript to JSON object serializer.
Is it possible to use Grails data binding using nested maps? Or do I really heave to implement that by hand for each domain class?
Thanks a lot,
Martin
Since this question got upvoted several times I would like to share what I did in the end:
Since I had some more requirements to be implemented like security etc. I implemented a service layer which hides the domain objects from the controllers. I introduced a "dynamic DTO layer" which translates Domain Objects to Groovy Maps which can be serialized easily using the standard serializers and which implements the updates manually. All the semi-automatic/meta-programming/command pattern/... based solutions I tried to implement failed at some point, mostly resulting in strange GORM errors or a lot of configuration code (and a lot of frustration). The update and serialization methods for the DTOs are fairly straightforward and could be implemented very quickly. It does not introduce a lot of duplicate code as well since you have to specify how your domain objects are serialized anyway if you don't want to publish your internal domain object structure. Maybe it's not the most elegant solution but it was the only solution which really worked for me. It also allows me to implement batch updates since the update logic is not connected to the http requests any more.
However I must say that I don't think that grails is the appropriate tech stack best suited for this kind of application, since it makes your application very heavy-weight and inflexbile. My experience is that once you start doing things which are not supported by the framework by default, it starts getting messy. Furthermore, I don't like the fact that the "repository" layer in grails essentially only exists as a part of the domain objects which introduced a lot of problems and resulted in several "proxy services" emulating a repository layer. If you start building an application using a json rest interface, I would suggest to either go for a very light-weight technology like node.js or, if you want to/have to stick to a java based stack, use standard spring framework + spring mvc + spring data with a nice and clean dto layer (this is what I've migrated to and it works like a charm). You don't have to write a lot of boilerplate code and you are completely in control of what's actually happening. Furthermore you get strong typing which increases developer productivity as well as maintainability and which legitimates the additional LOCs. And of course strong typing means strong tooling!
I started writing a blog entry describing the architecture I came up with (with a sample project of course), however I don't have a lot of time right now to finish it. When it's done I'm going to link to it here for reference.
Hope this can serve as inspiration for people experiencing similar problems.
Cheers!
It requires you to provide teh class name:
{ class:"SampleDomain", someString: "abc",
nest2: { class: "SampleDomainNested", someField:"def" }
}
I know, it requires different input that the output it produces.
As I mentioned in the comment earlier, you might be better off using the gson library.
Not sure why you wrote your own json marshaller, with xstream around.
See http://x-stream.github.io/json-tutorial.html
We have been very happy with xstream for our back end (grails based) services and this way you can render marshall in xml or json, or override the default marshalling for a specific object if you like.
Jettison seems to produce a more compact less human readable JSON and you can run into some library collision stuff, but the default internal json stream renderer is decent.
If you are going to publish the service to the public, you will want to take the time to return appropriate HTTP protocol responses for errors etc... ($.02)