[Proposition] Documentation of REST services

classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

[Proposition] Documentation of REST services

Jean SIMARD
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
[hidden email]
Research engineer at XWiki SAS
http://www.xwiki.com
Committer on the XWiki.org project
http://www.xwiki.org
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

vmassol
Administrator
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 ([hidden email](mailto:[hidden email])) 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
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Thomas Mortagne
Administrator
+1

On Wed, Dec 2, 2015 at 7:34 PM, [hidden email] <[hidden email]> 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 ([hidden email](mailto:[hidden email])) 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
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs



--
Thomas Mortagne
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Ecaterina Moraru (Valica)
+1

Thanks,
Caty

On Thu, Dec 3, 2015 at 10:15 AM, Thomas Mortagne <[hidden email]>
wrote:

> +1
>
> On Wed, Dec 2, 2015 at 7:34 PM, [hidden email] <[hidden email]>
> 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 ([hidden email](mailto:
> [hidden email])) 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
> > [hidden email]
> > http://lists.xwiki.org/mailman/listinfo/devs
>
>
>
> --
> Thomas Mortagne
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Eduard Moraru
In reply to this post by Thomas Mortagne
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).

Thanks,
Eduard

----------
[1]
http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI#HXWikiRESTfulAPIDocumentation
[2] http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI

On Thu, Dec 3, 2015 at 10:15 AM, Thomas Mortagne <[hidden email]>
wrote:

> +1
>
> On Wed, Dec 2, 2015 at 7:34 PM, [hidden email] <[hidden email]>
> 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 ([hidden email](mailto:
> [hidden email])) 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
> > [hidden email]
> > http://lists.xwiki.org/mailman/listinfo/devs
>
>
>
> --
> Thomas Mortagne
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Jean SIMARD
See below

On 03/12/2015 11:56, Eduard Moraru 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.
Yes, of course, and I can think also about 2 others pages that could
benefit that application too.
http://extensions.xwiki.org/xwiki/bin/view/Extension/Repository+Module
http://extensions.xwiki.org/xwiki/bin/view/Extension/XFF+REST+API
>
> +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).
Yes, I picture a livetable instead of the long list of entry points (and
the rest of the documentation stay as it is).

>
> Thanks,
> Eduard
>
> ----------
> [1]
> http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI#HXWikiRESTfulAPIDocumentation
> [2] http://platform.xwiki.org/xwiki/bin/view/Features/XWikiRESTfulAPI
>
> On Thu, Dec 3, 2015 at 10:15 AM, Thomas Mortagne <[hidden email]>
> wrote:
>
>> +1
>>
>> On Wed, Dec 2, 2015 at 7:34 PM, [hidden email] <[hidden email]>
>> 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 ([hidden email](mailto:
>> [hidden email])) 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
>>> [hidden email]
>>> http://lists.xwiki.org/mailman/listinfo/devs
>>
>>
>>
>> --
>> Thomas Mortagne
>> _______________________________________________
>> devs mailing list
>> [hidden email]
>> http://lists.xwiki.org/mailman/listinfo/devs
>>
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>

--
Jean Simard
[hidden email]
Research engineer at XWiki SAS
http://www.xwiki.com
Committer on the XWiki.org project
http://www.xwiki.org
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

vmassol
Administrator
In reply to this post by Eduard Moraru


On 3 Dec 2015 at 11:56:26, Eduard Moraru ([hidden email](mailto:[hidden email])) 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#HXWikiRESTfulAPIDocumentation
> [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, [hidden email]  
> > 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 ([hidden email](mailto:
> > [hidden email])) 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
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Jean SIMARD
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)?

Thanks,

On 03/12/2015 12:13, [hidden email] wrote:

>
>
> On 3 Dec 2015 at 11:56:26, Eduard Moraru ([hidden email](mailto:[hidden email])) 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#HXWikiRESTfulAPIDocumentation
>> [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, [hidden email]  
>>> 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 ([hidden email](mailto:
>>> [hidden email])) 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
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>

--
Jean Simard
[hidden email]
Research engineer at XWiki SAS
http://www.xwiki.com
Committer on the XWiki.org project
http://www.xwiki.org
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

vmassol
Administrator


On 3 Dec 2015 at 12:25:46, Jean SIMARD ([hidden email](mailto:[hidden email])) 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, [hidden email] wrote:
> >
> >
> > On 3 Dec 2015 at 11:56:26, Eduard Moraru ([hidden email](mailto:[hidden email])) 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#HXWikiRESTfulAPIDocumentation
> >> [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, [hidden email]
> >>> 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 ([hidden email](mailto:
> >>> [hidden email])) 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
> > [hidden email]
> > http://lists.xwiki.org/mailman/listinfo/devs
> >
>  
> --
> Jean Simard
> [hidden email]
> Research engineer at XWiki SAS
> http://www.xwiki.com
> Committer on the XWiki.org project
> http://www.xwiki.org
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Jean SIMARD
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, [hidden email] wrote:

>
>
> On 3 Dec 2015 at 12:25:46, Jean SIMARD
> ([hidden email](mailto:[hidden email])) 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, [hidden email] wrote:
>> >
>> >
>> > On 3 Dec 2015 at 11:56:26, Eduard Moraru
> ([hidden email](mailto:[hidden email])) 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#HXWikiRESTfulAPIDocumentation
>> >> [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, [hidden email]
>> >>> 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 ([hidden email](mailto:
>> >>> [hidden email])) 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
>> > [hidden email]
>> > http://lists.xwiki.org/mailman/listinfo/devs
>> >
>>
>> --
>> Jean Simard
>> [hidden email]
>> Research engineer at XWiki SAS
>> http://www.xwiki.com
>> Committer on the XWiki.org project
>> http://www.xwiki.org
>> _______________________________________________
>> devs mailing list
>> [hidden email]
>> http://lists.xwiki.org/mailman/listinfo/devs

--
Jean Simard
[hidden email]
Research engineer at XWiki SAS
http://www.xwiki.com
Committer on the XWiki.org project
http://www.xwiki.org

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Roman Muntyanu
In reply to this post by Jean SIMARD
Have you considered using Swagger ( http://swagger.io/ ) ?

e.g. http://petstore.swagger.io/
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

vmassol
Administrator


On 4 Dec 2015 at 15:31:57, coldserenity ([hidden email](mailto:[hidden email])) wrote:

> Have you considered using Swagger ( http://swagger.io/ ) ?

Thanks Coldserenity. Yes we have. See my comment on this thread (earlier posts).

Thanks
-Vincent

> e.g. http://petstore.swagger.io/
>
>
>
> --
> View this message in context: http://xwiki.475771.n2.nabble.com/Proposition-Documentation-of-REST-services-tp7597063p7597099.html

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Roman Muntyanu
Sorry did not notice :)
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Jean SIMARD
In reply to this post by Jean SIMARD
Up.

Is it possible for somebody to create a Github repository on
'xwiki-contrib' with the name 'application-rest-documentation' (or with
 better name if you think this one is not good)?  I guess we'll want a
Jira too.

Thanks,

On 04/12/2015 12:24, Jean SIMARD wrote:

> 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, [hidden email] wrote:
>>
>>
>> On 3 Dec 2015 at 12:25:46, Jean SIMARD
>> ([hidden email](mailto:[hidden email])) 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, [hidden email] wrote:
>>>>
>>>>
>>>> On 3 Dec 2015 at 11:56:26, Eduard Moraru
>> ([hidden email](mailto:[hidden email])) 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#HXWikiRESTfulAPIDocumentation
>>>>> [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, [hidden email]
>>>>>> 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 ([hidden email](mailto:
>>>>>> [hidden email])) 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
>>>> [hidden email]
>>>> http://lists.xwiki.org/mailman/listinfo/devs
>>>>
>>>
>>> --
>>> Jean Simard
>>> [hidden email]
>>> Research engineer at XWiki SAS
>>> http://www.xwiki.com
>>> Committer on the XWiki.org project
>>> http://www.xwiki.org
>>> _______________________________________________
>>> devs mailing list
>>> [hidden email]
>>> http://lists.xwiki.org/mailman/listinfo/devs
>

--
Jean Simard
[hidden email]
Research engineer at XWiki SAS
http://www.xwiki.com
Committer on the XWiki.org project
http://www.xwiki.org
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

vmassol
Administrator
Hi Jean,


On 7 Dec 2015 at 10:27:36, Jean SIMARD ([hidden email](mailto:[hidden email])) wrote:

> Up.
>  
> Is it possible for somebody to create a Github repository on
> 'xwiki-contrib' with the name 'application-rest-documentation' (or with
> better name if you think this one is not good)? I guess we'll want a
> Jira too.

Done:
- Github: https://github.com/xwiki-contrib/application-rest-documentation
- JIRA: http://jira.xwiki.org/browse/RDA

Thanks
-Vincent

> Thanks,
>  
> On 04/12/2015 12:24, Jean SIMARD wrote:
> > 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, [hidden email] wrote:
> >>
> >>
> >> On 3 Dec 2015 at 12:25:46, Jean SIMARD
> >> ([hidden email](mailto:[hidden email])) 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, [hidden email] wrote:
> >>>>
> >>>>
> >>>> On 3 Dec 2015 at 11:56:26, Eduard Moraru
> >> ([hidden email](mailto:[hidden email])) 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#HXWikiRESTfulAPIDocumentation
> >>>>> [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, [hidden email]
> >>>>>> 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 ([hidden email](mailto:
> >>>>>> [hidden email])) 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
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposition] Documentation of REST services

Jean SIMARD
OK, thanks.

I've release a version v0.1 of the extension.  So we could now install
it on platform.xwiki.org in order to start to replace the documentation.
 As told in a previous email, you'll find the content of the
documentation in the XAR RESTData.xar [2] from the page [1].

Thanks,

[1] http://dev.xwiki.org/xwiki/bin/view/Drafts/REST+AWM
[2] http://dev.xwiki.org/xwiki/bin/download/Drafts/REST+AWM/RESTData.xar

On 07/12/2015 10:35, [hidden email] wrote:

> Hi Jean,
>
>
> On 7 Dec 2015 at 10:27:36, Jean SIMARD
> ([hidden email](mailto:[hidden email])) wrote:
>
>> Up.
>>
>> Is it possible for somebody to create a Github repository on
>> 'xwiki-contrib' with the name 'application-rest-documentation' (or with
>> better name if you think this one is not good)? I guess we'll want a
>> Jira too.
>
> Done:
> - Github: https://github.com/xwiki-contrib/application-rest-documentation
> - JIRA: http://jira.xwiki.org/browse/RDA
>
> Thanks
> -Vincent
>
>> Thanks,
>>
>> On 04/12/2015 12:24, Jean SIMARD wrote:
>> > 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, [hidden email] wrote:
>> >>
>> >>
>> >> On 3 Dec 2015 at 12:25:46, Jean SIMARD
>> >> ([hidden email](mailto:[hidden email])) 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, [hidden email] wrote:
>> >>>>
>> >>>>
>> >>>> On 3 Dec 2015 at 11:56:26, Eduard Moraru
>> >> ([hidden email](mailto:[hidden email])) 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#HXWikiRESTfulAPIDocumentation
>> >>>>> [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, [hidden email]
>> >>>>>> 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
> ([hidden email](mailto:
>> >>>>>> [hidden email])) 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

--
Jean Simard
[hidden email]
Research engineer at XWiki SAS
http://www.xwiki.com
Committer on the XWiki.org project
http://www.xwiki.org
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs