fabiomaffioletti / jsondoc

Easily generate docs and playground for your RESTful API

JSONDoc

Official website: http://jsondoc.org

Want to contribute? Please follow these few guidelines:

1. Open issue on Github so that we can discuss it
2. When the issue is discussed and agreed, branch the code starting from the master branch, with branch name equals to "ISSUE-X" where X is the number of the issue on Github
3. Do not develop multiple features or bugfixes in the same branch, each feature/bugfix should have its branch and its code
4. Before submitting a pull request, please write unit tests. I think it's fair to say that pull requests without unit tests will not be merged
5. Submit the pull request

How to report a bug

Open an issue on Github in this form, where GIVEN is the set of preconditions to reproduce the bug, WHEN is the action that should be taken to reproduce the bug and THEN is the bug description, together with (if possible) screenshots and/or error messages/log that visually describe the bug.

GIVEN

• precondition 1
• precondition 2
• precondition n

WHEN

• action 1 AND/OR action 2 AND/OR action n

THEN

• bug description (with screenshots/messages/logs if possible)

jsondoc's Issues

Support query parameters: /users/{userId}.json?sort=name

Along with url variables, it would be good to support query parameters. For example:
/users/{userId}/pets.json?sort=name

Here, the query parameter sort needs to be documented.

It would be good to support query parameters in the 'playground'.

ApiObjectField does not handle wildcard type.

The following annotation results in a class cast exception:

@ApiObjectField
List<Message<?> messages;

Improvement with the PUT and POST methods

Now, when we create or update any object we put a JSON in this input text:

But we can’t know all the fields of this object:

Is it possible to add a relationship between service and objects in the POST and PUT methods? Also to change the input text to a textArea.
For example:

That is the Swagger implementation:

Thanks again.
Best regards, Mauro.

Class override in ApiBodyObject

Same as issue #38

POST with Content-Type application/json doesn't work in playground

The playground submits the content-type as form instead of application/json even though the method is annotated with consumes = ['application/json']. Therefore when used in the playground the application rejects the request.

Groups for apis and objects

Give the possibility to group api and objects to better visualize them in the UI

Parameters of Long[] or long[] throw exceptions

The code below throws an exception because it can't resolve the Long[]. Changing to long[] doesn't help.

@apimethod(path = '/graphQuery/labels', description = "Provides descriptive labels for nodes identified by id",
consumes = ['application/json'], verb = ApiVerb.POST, produces = ['application/json'])
@RequestMapping(value = "labels", method = RequestMethod.POST)
@responsebody

Create example for Spark

Support Patch request

We are using the documentation for our spring boot app, and would like to be able to document our patch endpoints. As we discussed over on #47, it sounds like you would like more than changes to ApiVerb, particularly some corresponding changes the ui project. Anything else you can think of?

Wildcard type check

Check that the wildcard type is correctly handled when generating *Doc objects. Already verified in ApiObjectFieldDoc. See issue #5 for more info.

Modify modules and master pom for maven-release-plugin

The current structure is not compliant to what maven-release-plugin expects to have to correctly perform: modify parent and master pom to be compliant.

ApiObject description not shown in UI

The description of the object is generated in the resulting json but not displayed in the UI

Relax check on description for ApiObjectField

Consider LinkedHashSet in ApiParamDoc.getApiParamDocs()

At line 35 of ApiParamDoc.java, please consider using LinkedHashSet instead to maintain order as per params in @ApiParams.

Cannot run the api project once added jsondoc dependency

Just i added the jsondoc dependencies to generate api docs, but i found once added them to project, the api project cannot be started.

My environments:
-Server: Tomcat 8.0.12
-Servlet Version: 3.0
-Spring Framework: 4.1.0.RELEASE
-Jsondoc version : 1.0.9

Tomcat console error logs:

10-Jan-2015 13:37:20.628 SEVERE [RMI TCP Connection(2)-127.0.0.1] org.apache.catalina.core.ContainerBase.addChildInternal ContainerBase.addChild: start:
org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[]]
at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:154)
at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:724)
at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:700)
at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:714)
at org.apache.catalina.startup.HostConfig.manageApp(HostConfig.java:1588)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:483)
at org.apache.tomcat.util.modeler.BaseModelMBean.invoke(BaseModelMBean.java:300)
at com.sun.jmx.interceptor.DefaultMBeanServerInterceptor.invoke(DefaultMBeanServerInterceptor.java:819)
at com.sun.jmx.mbeanserver.JmxMBeanServer.invoke(JmxMBeanServer.java:801)
at org.apache.catalina.mbeans.MBeanFactory.createStandardContext(MBeanFactory.java:463)
at org.apache.catalina.mbeans.MBeanFactory.createStandardContext(MBeanFactory.java:413)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:483)
at org.apache.tomcat.util.modeler.BaseModelMBean.invoke(BaseModelMBean.java:300)
at com.sun.jmx.interceptor.DefaultMBeanServerInterceptor.invoke(DefaultMBeanServerInterceptor.java:819)
at com.sun.jmx.mbeanserver.JmxMBeanServer.invoke(JmxMBeanServer.java:801)
at javax.management.remote.rmi.RMIConnectionImpl.doOperation(RMIConnectionImpl.java:1466)
at javax.management.remote.rmi.RMIConnectionImpl.access$300(RMIConnectionImpl.java:76)
at javax.management.remote.rmi.RMIConnectionImpl$PrivilegedOperation.run(RMIConnectionImpl.java:1307)
at javax.management.remote.rmi.RMIConnectionImpl.doPrivilegedOperation(RMIConnectionImpl.java:1399)
at javax.management.remote.rmi.RMIConnectionImpl.invoke(RMIConnectionImpl.java:828)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:483)
at sun.rmi.server.UnicastServerRef.dispatch(UnicastServerRef.java:323)
at sun.rmi.transport.Transport$1.run(Transport.java:178)
at sun.rmi.transport.Transport$1.run(Transport.java:175)
at java.security.AccessController.doPrivileged(Native Method)
at sun.rmi.transport.Transport.serviceCall(Transport.java:174)
at sun.rmi.transport.tcp.TCPTransport.handleMessages(TCPTransport.java:557)
at sun.rmi.transport.tcp.TCPTransport$ConnectionHandler.run0(TCPTransport.java:812)
at sun.rmi.transport.tcp.TCPTransport$ConnectionHandler.run(TCPTransport.java:671)
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
at java.lang.Thread.run(Thread.java:745)
Caused by: org.apache.catalina.LifecycleException: Failed to start component [org.apache.catalina.webresources.StandardRoot@30dcb2f2]
at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:154)
at org.apache.catalina.core.StandardContext.resourcesStart(StandardContext.java:4854)
at org.apache.catalina.core.StandardContext.startInternal(StandardContext.java:4983)
at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:150)
... 40 more
Caused by: org.apache.catalina.LifecycleException: Failed to initialize component [org.apache.catalina.webresources.JarResourceSet@2de5a780]
at org.apache.catalina.util.LifecycleBase.init(LifecycleBase.java:106)
at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:139)
at org.apache.catalina.webresources.StandardRoot.startInternal(StandardRoot.java:684)
at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:150)
... 43 more
Caused by: java.lang.IllegalArgumentException: java.util.zip.ZipException: error in opening zip file
at org.apache.catalina.webresources.JarResourceSet.initInternal(JarResourceSet.java:94)
at org.apache.catalina.util.LifecycleBase.init(LifecycleBase.java:102)
... 46 more
Caused by: java.util.zip.ZipException: error in opening zip file
at java.util.zip.ZipFile.open(Native Method)
at java.util.zip.ZipFile.(ZipFile.java:220)
at java.util.zip.ZipFile.(ZipFile.java:150)
at java.util.jar.JarFile.(JarFile.java:166)
at java.util.jar.JarFile.(JarFile.java:103)
at org.apache.catalina.webresources.JarResourceSet.initInternal(JarResourceSet.java:86)
... 47 more

Document 1.0.9 changes on website

Missing format for object field in jsondoc-ui

Document 1.0.6 changes on website

Show enum values

I have an enum class that I annotate with @ApiObject and it shows up fine but the enum values themselves don't show up.

Upgrade UI libraries

Upgrade bootstrap and jquery for jsondoc-ui

Enable Travis CI builds

Placeholders replacement in jsondoc-ui

When there is more than one parameter on the URL, only the last one is replaced.

Relax check on name for ApiObject

Lowercase the class name if not specified in the annotation

Handle ResponseEntity in jsondoc type builder

Is this project still active?

I found this project really useful. But still many things improvable. I wonder if this project is still active now.

Add default value to ApiParamDoc to map "default value" of spring mvc RequestParam

Spring Annotation Support

I know there is an outstanding pull request (#16) out there for spring annotation support, but it's missing tests, and doesn't merge anymore. I'd like to know what you think about a do-over on this.

My current thinking is that it should be part of the jsondoc-springmvc module, and basically just map the spring annotations over to the core classes. That way, non-spring folks can keep using the core library without pulling spring along for the ride.

The Api annotations would supplement things that are missing from the spring annotations (descriptions, groupings, etc.). Here are some specific things that I know need to be addressed in order to call this done. Other folks can add to this as needed.

• Support for ResponseEntity
• Opt-in for documentation (My current theory is that we would reuse the @apimethod and @Api annotations, with some tweaks (like not requiring the verb on @apimethod).
• Handling Spring defaults for the annotations (ex: verb defaults, content type defaults, produces defaults)

Thoughts/concerns?

Manage Basic Auth

Make the documentation aware of the authentication method used to call a method and modify the playground consequently.

Relax check on path and description on ApiMethod

Export to maven central repository

I suggest to prepare artifacts on central maven repository. It would be better for popularize library.

Produces and consumes must become Sets

Class override in ApiResponseObject

Give the possibility to specify the response object as part of the @ApiResponseObject annotation. For example:

@ApiResponseObject(City.class)

letting it possible to annotate old school servlets:

@ApiMethod(path = "/implicitResponseObject", verb = ApiVerb.GET, description = "a-test-method")
@ApiResponseObject(City.class)
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
...
}

Use the JSONDocTypeBuilder class to build the return type. Please create JSONDocNullType and use it as default class in the annotation declaration.

Support custom API response status.

Not all RESTful API methods return a 200 on success. For example, it is common to return a 201 for a successful POST.

It seems like this would be a good candidate for another annotation, although I am weary of suggesting the creation of annotations for everything :)

It would be very useful to support some indication in the UI of what the response status of an API call will be. (aside from the error response statuses).

ApiVerb default to GET

Support API versioning.

At eBuddy, we version our API with each release and provide backwards compatibility support for clients that still wish to use an old version of our API.

It would be useful to have a @apiversion annotation within the object model, and then to provide a way to 'filter' the JSONDoc to only include the elements that are relevant to a particular version.

Additionally:

• it would be good to see the 'since version' or 'until version' as part of the UI.

Api param at method level

Create a new annotation @ApiParams to allow specifying parameters on methods declaration instead of inside method signature. This is to let old style servlets document parameters in this way:

@ApiMethod(path = "/methodParams", verb = ApiVerb.GET, description = "a-test-method")
@ApiParams(apiparams = {
    @ApiParam(name = "name", paramType = ApiParamType.PATH, clazz = String.class),
    @ApiParam(name = "value", paramType = ApiParamType.PATH, clazz = String.class)
})
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
...
}

ApiObjectFieldDoc fails on Maps that contain either a key or value that is a ParameterizedType

When resolving a parameterized map in ApiObjectField, the key and value classes are pulled from the parameterizedType actualTypeArguments array and then cast to Class<?>. If the key or value is also a ParameterizedType, then this cast fails. To do this properly, the returned type should be recursively walked until all ParameterizedType returns are resolved. Either that or punt and use the raw type.

Specifically, I have a field declared as:
Map<String, Set> map;
I should expect getFieldObject to either return ["Map", "String", "Set", "map"] or ["Map", "String", "Set", "map"](or, at worse: ["Map", "String", null, "map"])

Handling of generics is probably present elsewhere in the code and might be best handled by a utility method that returns a Class for a given Type.

License?

I could not find any license info. Could you please add it to the reposiroty. Thanks.

Support for implicit request parameters

Instead of specifying request parameters one by one, Spring MVC allows a method to specify a holder object in the method parameters that gets bound to the request parameters. There is no way to document this type of parameters as of version 1.0.2.

Example:

@ResponseBody
@RequestMapping(method = RequestMethod.GET)
public List<SomeObject> list(@Valid FilterParameters params, HttpServletRequest request,
            HttpServletResponse response) throws Exception {
      return dao.getList(params.getSize(), params.getPage());
}

public static class FilterParameters {
        @NotNull
        private Integer size;
        @NotNull
        private Integer page;
}

Implicit parameters are also useful when request parameters are compulsory but are not used by the method explicitly. For example a REST endpoint is secured by a token that the clients must include as a request parameter in every request but the token is checked by a request interceptor and is not used directly by the method.

If you are interested in supporting this use case let me know. I might be able to implement it and send a pull request.

Would you accept a pull request to remove the servlet-api dependency?

Today I tried to use this w/ a springboot app and ran into a ton of pain. I finally realized it wouldn't boot because of a conflict between servlet-api versions. I was using 3.1 but this app today uses 2.4

Would you accept a PR to remove this hard coded dependency so others using springboot won't feel this pain?

https://github.com/fabiomaffioletti/jsondoc/blob/master/pom.xml#L123

Thank you for maintaining such a great OSS project !

allowedvalues in @ApiObjectField does not work?

I have added the below annotation but the allowed values does not show up in the documentation. @ApiObjectField(description = "Dummy.", allowedvalues = {"Test1", "Test2"})

Supporting file upload

Hi Fabio, does the JsonDoc supports the file upload testing as well, I mean we can test the API in the Test section, but is there a support for file uploading as well?

Add jsondocerrors/warnings/hints on ApiParamDoc, ApiMethodDoc, ApiObjectDoc

The problems with this project..

1. Almost no replies on issues and pull requests.
2. It uses release candidates in its dependencies.
3. Only one guy on the project and it seems like Fabio is to busy with other stuff.

So Fabio, will you let other into the project?

If not should we consider forking it and start a new project where we can get stuff done under a new name?

Any thoughts out there?

Multiple API methods with the same path

When you have a controller with multiple API Methods two or more of which contain the same path, but have different methods: only one of the API methods will be shown in the UI.

Upgrade to org.reflections 0.9.9

Please upgrade to org.reflections:reflections:0.9.9

0.9.9-RC1 Has a lot of problems in Java 8.

Refactoring of generic types checks

Code repetition spread in several classes to check generics. Merge methods into one and move it to an utils class.

Remove the need of ServletContext

ClasspathHelper.forWebInfClasses(servletContext)) is currently the path of the annotation scan, so there is a need of a valid ServletContext. Remove the need of it by letting the user specify which packages to scan.

Manage relaxed checks on ApiMethod path and description on ui

Autoselect Content-Type to first value in playground