4 Dec
2015
4 Dec
'15
12:24 p.m.
Hi devs,
OK, I've made a repository at
https://github.com/xwiki-labs/application-rest-documentation
(you may want to create one on xwiki-contrib and I'll push the data to it).
I'll be happy to do a first 0.1 release.
Also, I've written the data for the APIs described on the page [1].
You'll find the XAR here [2]. Once the extension
is released, somebody could install it on platform.xwiki.org and then
import this XAR to have some data.
[1] http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI
[2] http://dev.xwiki.org/xwiki/bin/download/Drafts/REST+AWM/RESTData.xar
Sincerely,
On 03/12/2015 12:32, vincent(a)massol.net wrote:
On 3 Dec 2015 at 12:25:46, Jean SIMARD
(jean.simard@xwiki.com(mailto:jean.simard@xwiki.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
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:
>
>> 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
> >
>
> --
> 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