Re: [xwiki-devs] [Proposition] Documentation of REST services

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, 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: >> >>> 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