question: api self documentation about extdirectspring

[ralscha]

Hi

Looks like a useful addition to the library. I personally don't have a need
for this but I'm sure this is useful in bigger project where a lot of
developer are involved. Especially when there is a developer team for the
client side and one for the server side.

If you want to contribute to the project the normal way on github is fork
the project and when finished send a pull request.
Here is a documentation about how this works:
https://help.github.com/articles/fork-a-repo

If you are not familiar with git you can just send me the changes and I
will then merge them into the code.

Ralph

On Wed, Oct 24, 2012 at 6:42 AM, dilbertside [email protected]:

Question

We are outsourcing part of the Extjs GUI, and in that effect we need to
document the api.js which interface with the web server.

I first gave the api-debug.js, but for performance reason and
confidentiality, property and method names are stripped to the strict
minimum (less than 6 character).

Itself without an accompanying documentation, the file is worthless, so
came to me the idea to document Ext Direct Spring with Documentation
Annotation which will be only used when the user request for the
api-debug.js to document the javascript Ext.Direct methods generated.

I made a draft of what could be such self-documentation without being too
intrusive to the current library:
example

@ExtDirectMethod(value = ExtDirectMethodType.FORM_POST, group = "standard",
documentation={
@ExtDirectParameters(params = { "id", "e", "p", "ic"}, values = {"id is
used to ...", "enum type", "product id", "blah blah"}),
@ExtDirectMethod("this method create a new user..."),
@ExtDirectReturn(properties= {"success", "errors"}, values={"true for
success, false otherwise", "list of failed fields"})
}
which will produce

......
/**
method to ...
@param https://github.com/param blah
@param https://github.com/param blah
@return https://github.com/return blah
*/
"cs" : [ {
"name" : "imp",
"len" : 0,
"formHandler" : true
}
.....
I reuse a notation use in @javax.persistence.Table

Would anyone make any use of that feature?
And if yes where can I contribute to develop that thing?

Kind regards,

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/44.

[dilbertside]

Hi,

I just uploaded a draft on the fork I made ([email protected]:dilbertside/extdirectspring.git).
I got troubles to produce a working unit test,
I copy to ch.ralscha.extdirectspring.controller.ApiControllerWithDocumentationTest some code.

In RemoteProviderSimple I add a method "methodDoc" with my doc annotations.
When I run junit, after the scan env test, api-debug.js is empty except namespace.
I'm pretty sure I miss something, but fail to see where.

Could you give me a hint, what's wrong in my unit test?

Thanks,

[ralscha]

The problem is that the method JsonHandler.writeValueAsString throws an
exception and because logging is turned off in logback.xml you don't see
anything.

To turn on logging change this in src/test/resources/logback.xml (OFF to
INFO)

The exception is: com.fasterxml.jackson.core.JsonGenerationException: Can
not write a field name, expecting a value

Haven't figured out what that means.

On Wed, Nov 14, 2012 at 3:00 AM, dilbertside [email protected]:

Hi,

I just uploaded a draft on the fork I made ([email protected]
:dilbertside/extdirectspring.git).
I got troubles to produce a working unit test,
I copy to
ch.ralscha.extdirectspring.controller.ApiControllerWithDocumentationTest
some code.

In RemoteProviderSimple I add a method "methodDoc" with my doc annotations.
When I run junit, after the scan env test, api-debug.js is empty except
namespace.
I'm pretty sure I miss something, but fail to see where.

Could you give me a hint, what's wrong in my unit test?

Thanks,

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/44#issuecomment-10352360.

[dilbertside]

I guess I know, I certainly mess up with the JsonSerializer.
I have a look at it.
Thanks

[dilbertside]

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7 elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size:<7> but was:<4> for <{'url'='/action/router', 'namespace'='actionns', 'type'='remoting', 'actions'={'remoteProviderSimple'=[{'name'='methodDoc', 'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**
* methodDoc: this method is used to test the documentation generation
* @author: dbs
* @Version: 0.1
*
* @param: [d] property d boolean
* @param: [e] array of integers
* @param: [b] property b string
* @param: [c] property c string
* @param: [a] property a integer
* @return
* [errors] list of failed fields
* [success] true for success, false otherwise
*/
{
"name" : "methodDoc",
"len" : 0
} ]
}
};

[ralscha]

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test sets up an
independent config object and compares the output with that object.

This code works:

private final static Logger logger =
LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);
//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard) comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc", false, null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns", "REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns", "REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside [email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7 elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns', 'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc', 'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/44#issuecomment-10354855.

[dilbertside]

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be implemented
differently as now I override JsonSerializer to add some comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js generation
extract comments in a second run, and after set an internal flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test sets up an
independent config object and compares the output with that object.

This code works:

private final static Logger logger =
LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);
//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard) comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc", false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7 elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns', 'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc', 'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

—
Reply to this email directly or view it on
GitHubhttps://github.com//issues/44#issuecomment-10354855.

—
Reply to this email directly or view it on GitHub
#44 (comment).

[ralscha]

Hi

That looks good.

I wonder if there is a possibility to dynamically add the @JsonSerialize
annotation
to the RemotingApi actions property. If that would be possible then we
could add another request mapping (for example: api-debug-doc.js) to the
ApiController and the code uses a different ObjectMapper, where the special
serializer for RemotingApi.actions is configured.

This way everything else would work as before and only the new request to
api-debug-doc.js would add the descriptions.

On Wed, Nov 14, 2012 at 8:48 AM, dilbertside [email protected]:

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be implemented
differently as now I override JsonSerializer to add some comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js generation
extract comments in a second run, and after set an internal flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test sets up an
independent config object and compares the output with that object.

This code works:

private final static Logger logger =
LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);
//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard) comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc", false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7 elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns', 'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc', 'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

—
Reply to this email directly or view it on
GitHub<
#44 (comment)
.

—
Reply to this email directly or view it on GitHub
<
https://github.com/ralscha/extdirectspring/issues/44#issuecomment-10355734>.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/44#issuecomment-10357747.

[ralscha]

There is indeed a solution for this. Just figured it out. The jackson
parser supports mixins.

I created a mixin that looks like this:
public abstract class RemotingApiMixin {
@JsonSerialize(using = MapActionSerializer.class)
abstract Map<String, List> getActions();
}

Then I removed the @JsonSerialize annotation from RemotingApi.actions
In the ApiControllerWithDocumentationTest class I added this line

routerController.getJsonHandler().getMapper().addMixInAnnotations(RemotingApi.class,
RemotingApiMixin.class);

This way it's possible to dynamically add the serializer.

On Wed, Nov 14, 2012 at 9:11 AM, Ralph Schaer [email protected] wrote:

Hi

That looks good.

I wonder if there is a possibility to dynamically add the @JsonSerialize
annotation
to the RemotingApi actions property. If that would be possible then we
could add another request mapping (for example: api-debug-doc.js) to the
ApiController and the code uses a different ObjectMapper, where the special
serializer for RemotingApi.actions is configured.

This way everything else would work as before and only the new request to
api-debug-doc.js would add the descriptions.

On Wed, Nov 14, 2012 at 8:48 AM, dilbertside [email protected]:

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be implemented
differently as now I override JsonSerializer to add some comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js generation
extract comments in a second run, and after set an internal flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test sets up an
independent config object and compares the output with that object.

This code works:

private final static Logger logger =
LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);
//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard) comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc", false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(), "remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7
elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns', 'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc', 'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

—
Reply to this email directly or view it on
GitHub<
#44 (comment)
.

—
Reply to this email directly or view it on GitHub
<
https://github.com/ralscha/extdirectspring/issues/44#issuecomment-10355734>.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/44#issuecomment-10357747.

[ralscha]

I changed the code base on this idea.

You can checkout the code in the branch 'comment' on [email protected]:
ralscha/extdirectspring.git.
I integrated your commits and added my changes on top of them.

Now a request to api-debug-doc.js adds docs and api-debug.js / api.js works
as before.
The code does not cache responses from api-debug-doc.js. Saves some memory.
Maybe we should even remove caching for api-debug.js responses. Somehow
this does not make any sense.

Unittest:

Without docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");

With docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug-doc.js");

On Wed, Nov 14, 2012 at 9:34 AM, Ralph Schaer [email protected] wrote:

There is indeed a solution for this. Just figured it out. The jackson
parser supports mixins.

I created a mixin that looks like this:
public abstract class RemotingApiMixin {
@JsonSerialize(using = MapActionSerializer.class)
abstract Map<String, List> getActions();
}

Then I removed the @JsonSerialize annotation from RemotingApi.actions
In the ApiControllerWithDocumentationTest class I added this line

routerController.getJsonHandler().getMapper().addMixInAnnotations(RemotingApi.class,
RemotingApiMixin.class);

This way it's possible to dynamically add the serializer.

On Wed, Nov 14, 2012 at 9:11 AM, Ralph Schaer [email protected]:

Hi

That looks good.

I wonder if there is a possibility to dynamically add the @JsonSerialize
annotation
to the RemotingApi actions property. If that would be possible then we
could add another request mapping (for example: api-debug-doc.js) to the
ApiController and the code uses a different ObjectMapper, where the special
serializer for RemotingApi.actions is configured.

This way everything else would work as before and only the new request to
api-debug-doc.js would add the descriptions.

On Wed, Nov 14, 2012 at 8:48 AM, dilbertside [email protected]:

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be implemented
differently as now I override JsonSerializer to add some comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js generation
extract comments in a second run, and after set an internal flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test sets up an
independent config object and compares the output with that object.

This code works:

private final static Logger logger =
LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);
//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard) comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc", false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API", "POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7
elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns', 'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc', 'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

—
Reply to this email directly or view it on
GitHub<
#44 (comment)
.

—
Reply to this email directly or view it on GitHub
<
https://github.com/ralscha/extdirectspring/issues/44#issuecomment-10355734>.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/44#issuecomment-10357747.

[dilbertside]

Great! Thanks.

I suggest to remove ch.ralscha.extdirectspring.util.ApiDocumentationTest
It was just a step toward my understanding of your unit test.
It is useless as the code as been copied to
ch.ralscha.extdirectspring.provider.RemoteProviderSimple

I made some clean up code removing useless imports,
I added more assertion test
and add the missing @deprecated for method obsolescence.

On 11/14/2012 05:38 PM, Ralph Schaer wrote:

I changed the code base on this idea.

You can checkout the code in the branch 'comment' on [email protected]:
ralscha/extdirectspring.git.
I integrated your commits and added my changes on top of them.

Now a request to api-debug-doc.js adds docs and api-debug.js / api.js
works
as before.
The code does not cache responses from api-debug-doc.js. Saves some
memory.
Maybe we should even remove caching for api-debug.js responses. Somehow
this does not make any sense.

Unittest:

Without docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");

With docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug-doc.js");

On Wed, Nov 14, 2012 at 9:34 AM, Ralph Schaer [email protected]
wrote:

There is indeed a solution for this. Just figured it out. The jackson
parser supports mixins.

I created a mixin that looks like this:
public abstract class RemotingApiMixin {
@JsonSerialize(using = MapActionSerializer.class)
abstract Map<String, List> getActions();
}

Then I removed the @JsonSerialize annotation from RemotingApi.actions
In the ApiControllerWithDocumentationTest class I added this line

routerController.getJsonHandler().getMapper().addMixInAnnotations(RemotingApi.class,
RemotingApiMixin.class);

This way it's possible to dynamically add the serializer.

On Wed, Nov 14, 2012 at 9:11 AM, Ralph Schaer
[email protected]:

Hi

That looks good.

I wonder if there is a possibility to dynamically add the
@JsonSerialize
annotation
to the RemotingApi actions property. If that would be possible then we
could add another request mapping (for example: api-debug-doc.js)
to the
ApiController and the code uses a different ObjectMapper, where the
special
serializer for RemotingApi.actions is configured.

This way everything else would work as before and only the new
request to
api-debug-doc.js would add the descriptions.

On Wed, Nov 14, 2012 at 8:48 AM, dilbertside
[email protected]:

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation
generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be implemented
differently as now I override JsonSerializer to add some comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js
generation
extract comments in a second run, and after set an internal flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test
sets up an
independent config object and compares the output with that object.

This code works:

private final static Logger logger =
LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);
//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard)
  comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc",
false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7
elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns',
'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc',
'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation
  generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

—
Reply to this email directly or view it on
GitHub<

#44 (comment)

.

—
Reply to this email directly or view it on GitHub
<

https://github.com/ralscha/extdirectspring/issues/44#issuecomment-10355734>.

—
Reply to this email directly or view it on
GitHubhttps://github.com//issues/44#issuecomment-10357747.

—
Reply to this email directly or view it on GitHub
#44 (comment).

[ralscha]

Hi

I'm wondering what's the state of this change. I would like to release a
version end of November and if everything is working we could add this
change to this release.

Ralph

On Wed, Nov 14, 2012 at 12:22 PM, dilbertside [email protected]:

Great! Thanks.

I suggest to remove ch.ralscha.extdirectspring.util.ApiDocumentationTest
It was just a step toward my understanding of your unit test.
It is useless as the code as been copied to
ch.ralscha.extdirectspring.provider.RemoteProviderSimple

I made some clean up code removing useless imports,
I added more assertion test
and add the missing @deprecated for method obsolescence.

On 11/14/2012 05:38 PM, Ralph Schaer wrote:

I changed the code base on this idea.

You can checkout the code in the branch 'comment' on [email protected]:
ralscha/extdirectspring.git.
I integrated your commits and added my changes on top of them.

Now a request to api-debug-doc.js adds docs and api-debug.js / api.js
works
as before.
The code does not cache responses from api-debug-doc.js. Saves some
memory.
Maybe we should even remove caching for api-debug.js responses. Somehow
this does not make any sense.

Unittest:

Without docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");

With docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug-doc.js");

On Wed, Nov 14, 2012 at 9:34 AM, Ralph Schaer [email protected]
wrote:

There is indeed a solution for this. Just figured it out. The jackson
parser supports mixins.

I created a mixin that looks like this:
public abstract class RemotingApiMixin {
@JsonSerialize(using = MapActionSerializer.class)
abstract Map<String, List> getActions();
}

Then I removed the @JsonSerialize annotation from RemotingApi.actions
In the ApiControllerWithDocumentationTest class I added this line

routerController.getJsonHandler().getMapper().addMixInAnnotations(RemotingApi.class,

RemotingApiMixin.class);

This way it's possible to dynamically add the serializer.

On Wed, Nov 14, 2012 at 9:11 AM, Ralph Schaer
[email protected]:

Hi

That looks good.

I wonder if there is a possibility to dynamically add the
@JsonSerialize
annotation
to the RemotingApi actions property. If that would be possible then we
could add another request mapping (for example: api-debug-doc.js)
to the
ApiController and the code uses a different ObjectMapper, where the
special
serializer for RemotingApi.actions is configured.

This way everything else would work as before and only the new
request to
api-debug-doc.js would add the descriptions.

On Wed, Nov 14, 2012 at 8:48 AM, dilbertside
[email protected]:

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation
generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be implemented
differently as now I override JsonSerializer to add some comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js
generation
extract comments in a second run, and after set an internal flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test
sets up an
independent config object and compares the output with that object.

This code works:

private final static Logger logger =
LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);
//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard)
  comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc",
false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should get 7
elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns',
'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc',
'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation
  generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

�
Reply to this email directly or view it on
GitHub<

#44 (comment)

.

�
Reply to this email directly or view it on GitHub
<

#44 (comment)
.

�
Reply to this email directly or view it on
GitHub<
#44 (comment)
.

�
Reply to this email directly or view it on GitHub
<
https://github.com/ralscha/extdirectspring/issues/44#issuecomment-10360168>.

�
Reply to this email directly or view it on GitHubhttps://github.com//issues/44#issuecomment-10362892.

[dilbertside]

Hi,

I'm fine with the current version, it fits my needs, and will hopefully
with some other library users.
I packaged a snapshot version which result you can see on the following
webapp prototype

I already use it for a week, and no problem so far.

My only concern is the unit testing, is it enough for your standard and
good to release it in the master branch?

Regards,

On 11/23/2012 06:17 PM, Ralph Schaer wrote:

Hi

I'm wondering what's the state of this change. I would like to release a
version end of November and if everything is working we could add this
change to this release.

Ralph

On Wed, Nov 14, 2012 at 12:22 PM, dilbertside
[email protected]:

Great! Thanks.

I suggest to remove
ch.ralscha.extdirectspring.util.ApiDocumentationTest
It was just a step toward my understanding of your unit test.
It is useless as the code as been copied to
ch.ralscha.extdirectspring.provider.RemoteProviderSimple

I made some clean up code removing useless imports,
I added more assertion test
and add the missing @deprecated for method obsolescence.

On 11/14/2012 05:38 PM, Ralph Schaer wrote:

I changed the code base on this idea.

You can checkout the code in the branch 'comment' on [email protected]:
ralscha/extdirectspring.git.
I integrated your commits and added my changes on top of them.

Now a request to api-debug-doc.js adds docs and api-debug.js / api.js
works
as before.
The code does not cache responses from api-debug-doc.js. Saves some
memory.
Maybe we should even remove caching for api-debug.js responses.
Somehow
this does not make any sense.

Unittest:

Without docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");

With docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug-doc.js");

On Wed, Nov 14, 2012 at 9:34 AM, Ralph Schaer [email protected]
wrote:

There is indeed a solution for this. Just figured it out. The
jackson
parser supports mixins.

I created a mixin that looks like this:
public abstract class RemotingApiMixin {
@JsonSerialize(using = MapActionSerializer.class)
abstract Map<String, List> getActions();
}

Then I removed the @JsonSerialize annotation from
RemotingApi.actions
In the ApiControllerWithDocumentationTest class I added this line

routerController.getJsonHandler().getMapper().addMixInAnnotations(RemotingApi.class,

RemotingApiMixin.class);

This way it's possible to dynamically add the serializer.

On Wed, Nov 14, 2012 at 9:11 AM, Ralph Schaer
[email protected]:

Hi

That looks good.

I wonder if there is a possibility to dynamically add the
@JsonSerialize
annotation
to the RemotingApi actions property. If that would be possible
then we
could add another request mapping (for example: api-debug-doc.js)
to the
ApiController and the code uses a different ObjectMapper, where
the
special
serializer for RemotingApi.actions is configured.

This way everything else would work as before and only the new
request to
api-debug-doc.js would add the descriptions.

On Wed, Nov 14, 2012 at 8:48 AM, dilbertside
[email protected]:

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation
generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be
implemented
differently as now I override JsonSerializer to add some
comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js
generation
extract comments in a second run, and after set an internal
flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test
sets up an
independent config object and compares the output with that
object.

This code works:

private final static Logger logger =

LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);

//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is
  com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard)
  comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new
MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new
MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc",
false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should
get 7
elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns',
'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc',
'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation
  generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

�
Reply to this email directly or view it on
GitHub<

#44 (comment)

.

�
Reply to this email directly or view it on GitHub
<

#44 (comment)

.

�
Reply to this email directly or view it on
GitHub<

#44 (comment)

.

�
Reply to this email directly or view it on GitHub
<

https://github.com/ralscha/extdirectspring/issues/44#issuecomment-10360168>.

�
Reply to this email directly or view it on
GitHubhttps://github.com//issues/44#issuecomment-10362892.

—
Reply to this email directly or view it on GitHub
#44 (comment).

[ralscha]

Don't worry about unit tests. We can improve them over time.
I maybe have time to write some tests before the end of the month.

Ralph

On Fri, Nov 23, 2012 at 11:39 AM, dilbertside [email protected]:

Hi,

I'm fine with the current version, it fits my needs, and will hopefully
with some other library users.
I packaged a snapshot version which result you can see on the following
webapp prototype
https://diic36.com/mangrep/api-debug-doc.js?group=standard

I already use it for a week, and no problem so far.

My only concern is the unit testing, is it enough for your standard and
good to release it in the master branch?

Regards,

On 11/23/2012 06:17 PM, Ralph Schaer wrote:

Hi

I'm wondering what's the state of this change. I would like to release a
version end of November and if everything is working we could add this
change to this release.

Ralph

On Wed, Nov 14, 2012 at 12:22 PM, dilbertside
[email protected]:

Great! Thanks.

I suggest to remove
ch.ralscha.extdirectspring.util.ApiDocumentationTest
It was just a step toward my understanding of your unit test.
It is useless as the code as been copied to
ch.ralscha.extdirectspring.provider.RemoteProviderSimple

I made some clean up code removing useless imports,
I added more assertion test
and add the missing @deprecated for method obsolescence.

On 11/14/2012 05:38 PM, Ralph Schaer wrote:

I changed the code base on this idea.

You can checkout the code in the branch 'comment' on [email protected]:
ralscha/extdirectspring.git.
I integrated your commits and added my changes on top of them.

Now a request to api-debug-doc.js adds docs and api-debug.js / api.js
works
as before.
The code does not cache responses from api-debug-doc.js. Saves some
memory.
Maybe we should even remove caching for api-debug.js responses.
Somehow
this does not make any sense.

Unittest:

Without docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug.js");

With docs:
MockHttpServletRequest request = new MockHttpServletRequest("GET",
"/action/api-debug-doc.js");

On Wed, Nov 14, 2012 at 9:34 AM, Ralph Schaer <[email protected]

wrote:

There is indeed a solution for this. Just figured it out. The
jackson
parser supports mixins.

I created a mixin that looks like this:
public abstract class RemotingApiMixin {
@JsonSerialize(using = MapActionSerializer.class)
abstract Map<String, List> getActions();
}

Then I removed the @JsonSerialize annotation from
RemotingApi.actions
In the ApiControllerWithDocumentationTest class I added this line

routerController.getJsonHandler().getMapper().addMixInAnnotations(RemotingApi.class,

RemotingApiMixin.class);

This way it's possible to dynamically add the serializer.

On Wed, Nov 14, 2012 at 9:11 AM, Ralph Schaer
[email protected]:

Hi

That looks good.

I wonder if there is a possibility to dynamically add the
@JsonSerialize
annotation
to the RemotingApi actions property. If that would be possible
then we
could add another request mapping (for example: api-debug-doc.js)
to the
ApiController and the code uses a different ObjectMapper, where
the
special
serializer for RemotingApi.actions is configured.

This way everything else would work as before and only the new
request to
api-debug-doc.js would add the descriptions.

On Wed, Nov 14, 2012 at 8:48 AM, dilbertside
[email protected]:

Thank you very much.
That was it.

I have 2 more questions:
I will add some unit tests related to that documentation
generation bit
specifically to be sure it generates properly.
Will run all unit tests to spot troubles

Question 1:
What would like to see as unit test to check that the rest of the
library is not impacted negatively with this feature.

Question 2:
That would be neat and clean to have a configuration flag to
deactivate/activate this feature.
But unfortunately as the class MethodInfo is called by
onApplicationEvent, I don't see a way to cancel the generation.
Perhaps the api json documentation generation should be
implemented
differently as now I override JsonSerializer to add some
comments for
each methods automatically.
maybe on debug mode, we can afford to waste time and through the
apiCache.INSTANCE in the api controller before api-debug.js
generation
extract comments in a second run, and after set an internal
flag to
speed up things.
The configuration flag could be useful in that case.
What do you think?

On 11/14/2012 01:27 PM, Ralph Schaer wrote:

The problem was the configuration. The api controller reads the
configuration object from the routercontroller, but the test
sets up an
independent config object and compares the output with that
object.

This code works:

private final static Logger logger =

LoggerFactory.getLogger(ApiControllerWithDocumentationTest.class);
@Autowired
private ApplicationContext applicationContext;

@Autowired
private ApiController apiController;

@Autowired
private RouterController routerController;

@before
public void setupApiController() throws Exception {
ApiCache.INSTANCE.clear();

routerController.getConfiguration().setTimeout(15000);
routerController.getConfiguration().setEnableBuffer(false);
routerController.getConfiguration().setMaxRetries(5);
routerController.getConfiguration().setStreamResponse(true);

//routerController.getConfiguration().setApiDocumentation(true);
}

/**

• to test the following
• need to activate Feature 'ALLOW_COMMENTS' for jackson parser
• typical error is
  com.fasterxml.jackson.core.JsonParseException:
  Unexpected character ('/' (code 47)): maybe a (non-standard)
  comment?
  *
• @throws IOException
  */
  @test
  public void testGroupDoc() throws IOException {

MockHttpServletRequest request = new
MockHttpServletRequest("GET",
"/action/api-debug.js");
MockHttpServletResponse response = new
MockHttpServletResponse();
//apiController.api(null, null, null, null, null, "groupdoc",
false,
null,
request, response);
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
logger.info("\n\n"+response.getContentAsString()+"\n\n");
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");

request = new MockHttpServletRequest("GET", "/action/api.js");
response = new MockHttpServletResponse();
apiController.api("Ext.ns", "actionns", "REMOTING_API",
"POLLING_URLS",
"SSE", "groupdoc", false, null, request, response);
ApiControllerTest.compare(response.getContentAsString(),
response.getContentType(),
ApiControllerTest.group1ApisWithDoc("actionns"), "Ext.ns",
"REMOTING_API",
"POLLING_URLS", "SSE", routerController.getConfiguration(),
"remoting");
}

On Wed, Nov 14, 2012 at 5:23 AM, dilbertside
[email protected]:

First draft working. But unit test fails.

In the following error, I cannot understand why I should
get 7
elements

assertion failed with
NOOFCONFIG: 3
url->/action/router
namespace->actionns
type->remoting
actions->{remoteProviderSimple=[{name=methodDoc, len=0}]}

java.lang.AssertionError: expected size: but was: for
<{'url'='/action/router', 'namespace'='actionns',
'type'='remoting',
'actions'={'remoteProviderSimple'=[{'name'='methodDoc',
'len'=0}]}}>

with the following api-debug.js generated:

Ext.ns('Ext.ns');

Ext.ns('actionns');

Ext.ns.REMOTING_API = {
"url" : "/action/router",
"namespace" : "actionns",
"type" : "remoting",
"actions" : {
"remoteProviderSimple" : [
/**

• methodDoc: this method is used to test the documentation
  generation
• @author https://github.com/author: dbs
• @Version https://github.com/version: 0.1
  *
• @param https://github.com/param: [d] property d boolean
• @param https://github.com/param: [e] array of integers
• @param https://github.com/param: [b] property b string
• @param https://github.com/param: [c] property c string
• @param https://github.com/param: [a] property a integer
• @return https://github.com/return
• [errors] list of failed fields
• [success] true for success, false otherwise
  */
  {
  "name" : "methodDoc",
  "len" : 0
  } ]
  }
  };

�
Reply to this email directly or view it on
GitHub<

#44 (comment)

.

�
Reply to this email directly or view it on GitHub
<

#44 (comment)

.

�
Reply to this email directly or view it on
GitHub<

#44 (comment)

.

�
Reply to this email directly or view it on GitHub
<

#44 (comment)
.

�
Reply to this email directly or view it on
GitHub<
#44 (comment)
.

�
Reply to this email directly or view it on GitHub
<
https://github.com/ralscha/extdirectspring/issues/44#issuecomment-10655254>.

�
Reply to this email directly or view it on GitHubhttps://github.com//issues/44#issuecomment-10655874.

[ralscha]

I integrated your changes into the 'next' branch. I also created a new 1.2.3-SNAPSHOT release.
https://oss.sonatype.org/content/repositories/snapshots/ch/ralscha/extdirectspring/1.2.3-SNAPSHOT/extdirectspring-1.2.3-20121124.023509-13.jar

Would be nice if you could test this release. To make sure that all your changes are merged.

[ralscha]

Version 1.2.3 released