3 Dec
2015
3 Dec
'15
12:32 p.m.
On 3 Dec 2015 at 12:25:46, Jean SIMARD
(jean.simard@xwiki.com(mailto:jean.simard@xwiki.com)) wrote:
Hi,
If that's OK, I'll create a repo on Github
xwiki-contrib/application-rest. Should we create a Jira at this point
(AWMREST or just REST)?
For me the app name should be something like “REST Document Application”.
Thanks
-Vincent
Thanks,
On 03/12/2015 12:13, vincent(a)massol.net wrote:
On 3 Dec 2015 at 11:56:26, Eduard Moraru
(enygma2002@gmail.com(mailto:enygma2002@gmail.com)) wrote:
--
Jean Simard
jean.simard(a)xwiki.com
Research engineer at XWiki SAS
http://www.xwiki.com
Committer on the XWiki.org project
http://www.xwiki.org
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs Hi,
Nice initiative.
I guess you should also mention that your proposal is only about replacing
the API Documentation section[1] inside the REST documentation page[2] and
not about replacing the whole documentation page with this application. As
far as I can see, this application is highly focused/structured on the API,
but the documentation page contains much more than just API and we
should/could not force all the page's sections into a flat-structured
livetable.
+1 to integrating the API application into the documentation page and not
the other way around (i.e. not as Vincent's point 3), above).
To clarify, "migrate REST doc to it progressively” obviously means keeping the REST
page entry point we have and move the endpoints API inside it to this app, i.e. have that
livetable displayed inside that page (potentially using an {{include/}}).
Note: I have worked with Jean on this and our goal was only to provide a way to document
the endpoints in a more scalable way. Note that ideally each extension's documentation
should provide its own REST endpoint XObject. However I’m pretty sure Jean has not
implemented the JSON generation for the Livetable using SOLR Search ATM so it won’t work
across subwikis (ie for example if an extension on e.x.o adds some REST endpoints it won’t
be displayed).
@Jean: if you want to make this scalable and generic, you should add a new XProperty for
the Extension id of the extension contributing the REST endpoint.
Note: Another idea for the future is to make this app available inside the wiki as part
of the Help Application for example (or as a dependency of it) so that the REST endpoints
are self-documented in your wiki. Since the REST APIs you have in your wiki depend on the
extensions that you have installed.
Note: We also discussed using a standard format/tool such as Swagger. We decided not to
go this route (but I did very little research on this myself) because AFAIK swagger and
other tools like this generate doc based on sources. We need to check if there exists some
REST-generation tool that discover endpoints at runtime and not based on java sources.
Thanks
-Vincent
Thanks,
Eduard
----------
[1]
http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI#HXWikiRES…
[2] http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI
On Thu, Dec 3, 2015 at 10:15 AM, Thomas Mortagne
wrote:
> +1
>
> On Wed, Dec 2, 2015 at 7:34 PM, vincent(a)massol.net
> wrote:
>> Hi Jean,
>>
>> Very nice, +1 to start using it and tune it as we progress.
>>
>> I think the steps would be:
>>
>> 1) Commit the app in xwiki-contrib
>> 2) Install it in xwiki.org (if others agree)
>> 3) migrate REST doc to it progressively
>>
>> Thanks
>> -Vincent
>>
>> On 2 Dec 2015 at 19:07:28, Jean SIMARD (jean.simard(a)xwiki.com(mailto:
> jean.simard(a)xwiki.com)) wrote:
>>
>>> Hi devs,
>>>
>>> REST service of XWiki is pretty good. And the documentation is almost
>>> complete... but it's a long, long page, a bit difficult to read and to
>>> find the information.
>>>
>>> But hey, guess what? XWiki is a perfect tool to document that. So I've
>>> started a prototype with AWM to do that.
>>>
>>> On the following link, you'll find a few images and a XAR with the
>>> application and a few samples of REST documentation.
>>>
>>> http://dev.xwiki.org/xwiki/bin/view/Drafts/REST+AWM
>>>
>>> Tell me what you think.
>>>
>>> Thanks,
>>> --
>>> Jean Simard
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs