1

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?

Vidia
  • 471
  • 5
  • 17
  • Which JAX-RS implementation are you using? Have a look at the approach that Jersey uses to generate WADL (https://jersey.java.net/documentation/latest/wadl.html). You may find it helpful. – Alexey Gavrilov Jul 18 '14 at 20:45
  • That looks helpful for reading resources I think I may change to that for the resource processing, but I still need to read the javadoc, which will be gone at that point. – Vidia Jul 21 '14 at 13:45
  • The Jersey team has implemented a doclet that stores the javadoc information for further WADL generation. Have a look: https://java.net/projects/jersey/sources/svn/show/trunk/jersey/samples/generate-wadl – Alexey Gavrilov Jul 21 '14 at 15:09

1 Answers1

0

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

Community
  • 1
  • 1
bhantol
  • 9,368
  • 7
  • 44
  • 81