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