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 _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
