Hi, Here are some suggestions when preparing the documents for the REST API. There are various ways of doing this. Embed swagger into a frame is the first method [1]. As the second method, swagger APIs can be hosted [2] as well. Also, if you like, you can generate static html pages from swagger [3]. Through a proper evaluation it would be easier to identify which method is the best for your scenario.
Since the whole platform is moving towards the REST API, better to have a consistency when designing the API, API docs and other relevant components. In the viewpoint of a user, it would be helpful for them if we can add some instructions to invoke the REST API via Soap-UI, Advanced REST client, cURL or any other popular tools that are used widely. [1] https://confluence.atlassian.com/display/CONFKB/How+to+put+an+IFrame+into+Confluence [2] http://www.aerobatic.com/blog/hosting-swagger-api-documentation-wth-bitbucket.html [3] http://stackoverflow.com/questions/26605217/generate-static-docs-with-swagger Thanks. On Tue, Dec 15, 2015 at 12:44 PM, Sanjeewa Malalgoda <sanje...@wso2.com> wrote: > As a platform we are moving more towards REST API and we have already > implemented most of the required components for complete story. > If you are looking for securing REST APIs with Basic Auth, OAuth, XACML > then all these feature are developed as CXF interceptors. > So do not spent time to reinvent them and just use available features and > fix if there any missing parts. > > And OAuth application registration for them also available as installable > feature. > As malintha said if you start with swagger API document then you can > generate REST web service, client samples and document (with already > developed plugins). > > Thanks, > sanjeewa. > > > On Sun, Dec 13, 2015 at 10:37 AM, Malintha Amarasinghe <malint...@wso2.com > > wrote: > >> Hi Natasha, >> >> Giving you a small suggestion to port the documentation to Swagger [1] as >> there are many advantages. >> >> 1. It is a well structured way of documenting APIs and it is used by many >> organizations. >> >> 2. Users of your API can use the swagger doc to generate clients. There >> are lots of tools that can do it for them including swagger-code-gen tool >> [2]. They supports many languages including HTML/javascript, Java. >> >> 3. Swagger doc can be used to generate server code >> skeleton. swagger-code-gen [2] includes that capability also. We used a >> customized version of it which is swagger2cxf-maven-plugin [3] to generate >> CXF server code when we were implementing the new REST API for API Manager. >> >> 4. Swagger doc can be used to generate HTML documentation too. Please >> note we are still in the process of doing it. Have a look at below links >> they are completely auto generated from Swagger docs, (Please ignore some >> characters like \n and * they should be corrected from the code generator. >> :) And we are yet to do some beatifications etc ) >> >> http://apidocs.wso2.com/rest/apim/store/v1/docs >> http://apidocs.wso2.com/rest/apim/publisher/v1/docs >> >> Please have a look at [4] and [5], what we have written for the REST API >> which might help you. You can use [6] as a tool for documenting. You might >> also have seen before an example of swagger-ui [7] which users can directly >> use the Swagger doc to invoke the API. >> >> Thanks, >> Malintha >> >> [1] http://swagger.io/specification/ >> [2] https://github.com/swagger-api/swagger-codegen >> [3] https://github.com/hevayo/swagger2cxf-maven-plugin >> [4] >> https://github.com/wso2/carbon-apimgt/blob/release-1.10.x/components/apimgt/org.wso2.carbon.apimgt.rest.api.store/src/main/resources/store-api.yaml >> [5] >> https://github.com/wso2/carbon-apimgt/blob/release-1.10.x/components/apimgt/org.wso2.carbon.apimgt.rest.api.publisher/src/main/resources/publisher-api.yaml >> [6] http://editor.swagger.io/ >> [7] http://petstore.swagger.io >> >> <http://petstore.swagger.io/>-- >> Malintha Amarasinghe >> Software Engineer >> *WSO2, Inc. - lean | enterprise | middleware* >> http://wso2.com/ >> >> Mobile : +94 712383306 >> >> On Fri, Dec 11, 2015 at 6:05 PM, Natasha Wijesekara <nata...@wso2.com> >> wrote: >> >>> I created a documentation jira and attached the api doc. >>> >>> Thanks >>> Natasha >>> >>> On Fri, Dec 11, 2015 at 4:23 PM, Nandika Jayawardana <nand...@wso2.com> >>> wrote: >>> >>>> Lets attach the doc to a documentation jira so that api is added to the >>>> documentation. >>>> >>>> Regards >>>> Nandika >>>> >>>> On Thu, Dec 10, 2015 at 7:03 PM, Natasha Wijesekara <nata...@wso2.com> >>>> wrote: >>>> >>>>> Hi, >>>>> >>>>> @Vinod, I used the format given in the Activiti rest api documentation >>>>> to include the response codes. >>>>> >>>>> @Nuwan, I have updated the user guide with the response codes and the >>>>> sample success responses. >>>>> >>>>> >>>>> Thanks, >>>>> Natasha >>>>> >>>>> On Thu, Dec 10, 2015 at 8:39 AM, Vinod Kavinda <vi...@wso2.com> wrote: >>>>> >>>>>> Hi Natasha, >>>>>> You can use the format used in Activiti rest api documentations [1] >>>>>> for this also. It includes response codes and sample success responses. >>>>>> >>>>>> @Dinithi, we are doing basic authentication using the security >>>>>> handler [2] AFAIK. >>>>>> >>>>>> [1] - http://www.activiti.org/userguide/#_get_a_deployment >>>>>> [2] - >>>>>> https://github.com/wso2/carbon-business-process/blob/master/components/bpmn/bpmn-rest/src/main/java/org/wso2/carbon/bpmn/rest/security/AuthenticationHandler.java >>>>>> >>>>>> Regards, >>>>>> Vinod Kavinda >>>>>> >>>>>> On Thu, Dec 10, 2015 at 7:30 AM, Dinithi De Silva <dinit...@wso2.com> >>>>>> wrote: >>>>>> >>>>>>> Hi Natasha, >>>>>>> >>>>>>> How are you going to ensure the security of the APIs? Have you >>>>>>> thought of using any security models? >>>>>>> >>>>>>> You can use permission/role based model in order to achieve this. >>>>>>> Just make sure which APIs need the administrative privileges. >>>>>>> >>>>>>> Thanks. >>>>>>> >>>>>>> >>>>>>> On Wed, Dec 9, 2015 at 9:30 PM, Nuwan Pallewela <nuw...@wso2.com> >>>>>>> wrote: >>>>>>> >>>>>>>> Hi Natasha, >>>>>>>> >>>>>>>> Great work. >>>>>>>> What happens if an invalid request or request with an illegal >>>>>>>> argument sent to the API ? >>>>>>>> It is better to have those response messages or response status >>>>>>>> code also in the documentation. >>>>>>>> >>>>>>>> Thanks, >>>>>>>> Nuwan >>>>>>>> >>>>>>>> On Wed, Dec 9, 2015 at 5:08 PM, Natasha Wijesekara < >>>>>>>> nata...@wso2.com> wrote: >>>>>>>> >>>>>>>>> Hi, >>>>>>>>> >>>>>>>>> I documented a user guide which contains details about the new >>>>>>>>> rest API implemented to generate the statistics for bpmn. >>>>>>>>> Appreciate any suggestions and comments. >>>>>>>>> >>>>>>>>> Thanks, >>>>>>>>> Natasha >>>>>>>>> >>>>>>>>> On Tue, Dec 8, 2015 at 4:44 PM, Vinod Kavinda <vi...@wso2.com> >>>>>>>>> wrote: >>>>>>>>> >>>>>>>>>> [Adding Architecture group] >>>>>>>>>> >>>>>>>>>> On Tue, Dec 8, 2015 at 2:45 PM, Natasha Wijesekara < >>>>>>>>>> nata...@wso2.com> wrote: >>>>>>>>>> >>>>>>>>>>> Hi , >>>>>>>>>>> >>>>>>>>>>> Currently the statistics generated for the bpmn-explorer is >>>>>>>>>>> generated using jaggery. When the work load is high, the >>>>>>>>>>> bpmn-explorer >>>>>>>>>>> takes a longer time to generate these statistics which causes >>>>>>>>>>> performance >>>>>>>>>>> issues. >>>>>>>>>>> >>>>>>>>>>> As a solution I am working a new stats REST api to generate >>>>>>>>>>> these statistics at the back-end. This reduces the work load and >>>>>>>>>>> thereby >>>>>>>>>>> solves the performance issues caused during peak times (when the >>>>>>>>>>> workload >>>>>>>>>>> is at its maximum). >>>>>>>>>>> >>>>>>>>>>> After taking in data about the bpmn processes, tasks and users >>>>>>>>>>> involved, the api processes these data into meaningful >>>>>>>>>>> statistics.These >>>>>>>>>>> statistics generated is used in the bpmn-explorer reporting >>>>>>>>>>> dashboard to >>>>>>>>>>> generate the statistical graphs. >>>>>>>>>>> >>>>>>>>>>> The statistics generated includes: >>>>>>>>>>> >>>>>>>>>>> 1) Average time duration for all completed processes. >>>>>>>>>>> The user has the option to either view all completed processes >>>>>>>>>>> or the top 10 processes which finished within a short time duration >>>>>>>>>>> or the >>>>>>>>>>> top 10 processes which took a long time duration to finish. >>>>>>>>>>> >>>>>>>>>>> 2) Average time duration of tasks of a completed process. >>>>>>>>>>> The user can select the completed process from the combo box and >>>>>>>>>>> view the average time duration. >>>>>>>>>>> >>>>>>>>>>> 3) User and the no. of tasks he/she has completed upto now. >>>>>>>>>>> >>>>>>>>>>> 4) Average time taken by each user to complete the tasks >>>>>>>>>>> assigned to him/her. >>>>>>>>>>> >>>>>>>>>>> 5) Task demand variation over time i.e. no. of tasks started and >>>>>>>>>>> no. of tasks completed in each month. This is useful for resource >>>>>>>>>>> allocation purposes. >>>>>>>>>>> >>>>>>>>>>> 6) Process demand variation over time i.e. no. of processes >>>>>>>>>>> started and no. of processes completed in each month regardless of a >>>>>>>>>>> specific user. This is useful for resource allocation purposes. >>>>>>>>>>> >>>>>>>>>>> 7) User Performance i.e. Task demand variation of users >>>>>>>>>>> separately over time i.e. no. of tasks started and no. of tasks >>>>>>>>>>> completed >>>>>>>>>>> in each month. This is useful for resource allocation purposes. >>>>>>>>>>> >>>>>>>>>>> I have attached the class diagram of the REST api. The new stats >>>>>>>>>>> REST api will be integrated with the existing bpmn REST api. >>>>>>>>>>> Appreciate any suggestions and comments. >>>>>>>>>>> >>>>>>>>>>> Thanks, >>>>>>>>>>> -- >>>>>>>>>>> *Natasha Wijesekare* >>>>>>>>>>> >>>>>>>>>>> *Software Engineering Intern, WSO2 Inc: http://wso2.com >>>>>>>>>>> <http://wso2.com/>* >>>>>>>>>>> *email : nata...@wso2.com <nata...@wso2.com>* >>>>>>>>>>> *mobile: +94 771358651 <%2B94%20771358651>* >>>>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> -- >>>>>>>>>> Vinod Kavinda >>>>>>>>>> Software Engineer >>>>>>>>>> *WSO2 Inc. - lean . enterprise . middleware >>>>>>>>>> <http://www.wso2.com>.* >>>>>>>>>> Mobile : +94 (0) 712 415544 >>>>>>>>>> Blog : http://soatechflicks.blogspot.com/ >>>>>>>>>> >>>>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> -- >>>>>>>>> *Natasha Wijesekare* >>>>>>>>> >>>>>>>>> *Software Engineering Intern, WSO2 Inc: http://wso2.com >>>>>>>>> <http://wso2.com/>* >>>>>>>>> *email : nata...@wso2.com <nata...@wso2.com>* >>>>>>>>> *mobile: +94 771358651 <%2B94%20771358651>* >>>>>>>>> >>>>>>>>> _______________________________________________ >>>>>>>>> Dev mailing list >>>>>>>>> Dev@wso2.org >>>>>>>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>>>>>>> >>>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> -- >>>>>>>> ---------------------------------------------------------- >>>>>>>> >>>>>>>> *Nuwan Chamara Pallewela* >>>>>>>> >>>>>>>> >>>>>>>> *Software Engineer* >>>>>>>> >>>>>>>> *WSO2, Inc. *http://wso2.com >>>>>>>> *lean . enterprise . middleware* >>>>>>>> >>>>>>>> Email *nuw...@wso2.com <nuw...@wso2.com>* >>>>>>>> Mobile *+94719079739 <%2B94719079739>@* >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> _______________________________________________ >>>>>>>> Architecture mailing list >>>>>>>> architect...@wso2.org >>>>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>>>>> >>>>>>>> >>>>>>> >>>>>>> >>>>>>> -- >>>>>>> *Dinithi De Silva* >>>>>>> Associate Software Engineer, WSO2 Inc. >>>>>>> m:+94716667655 | e:dinit...@wso2.com | w: www.wso2.com >>>>>>> | a: #20, Palm Grove, Colombo 03 >>>>>>> >>>>>>> _______________________________________________ >>>>>>> Dev mailing list >>>>>>> Dev@wso2.org >>>>>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>>>>> >>>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> Vinod Kavinda >>>>>> Software Engineer >>>>>> *WSO2 Inc. - lean . enterprise . middleware <http://www.wso2.com>.* >>>>>> Mobile : +94 (0) 712 415544 >>>>>> Blog : http://soatechflicks.blogspot.com/ >>>>>> >>>>>> >>>>>> _______________________________________________ >>>>>> Architecture mailing list >>>>>> architect...@wso2.org >>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>>> >>>>>> >>>>> >>>>> >>>>> -- >>>>> *Natasha Wijesekare* >>>>> >>>>> *Software Engineering Intern, WSO2 Inc: http://wso2.com >>>>> <http://wso2.com/>* >>>>> *email : nata...@wso2.com <nata...@wso2.com>* >>>>> *mobile: +94 771358651 <%2B94%20771358651>* >>>>> >>>> >>>> >>>> >>>> -- >>>> Nandika Jayawardana >>>> WSO2 Inc ; http://wso2.com >>>> lean.enterprise.middleware >>>> >>> >>> >>> >>> -- >>> *Natasha Wijesekare* >>> >>> *Software Engineering Intern, WSO2 Inc: http://wso2.com >>> <http://wso2.com/>* >>> *email : nata...@wso2.com <nata...@wso2.com>* >>> *mobile: +94 771358651 <%2B94%20771358651>* >>> >>> _______________________________________________ >>> Dev mailing list >>> Dev@wso2.org >>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>> >>> >> >> >> -- >> Malintha Amarasinghe >> Software Engineer >> *WSO2, Inc. - lean | enterprise | middleware* >> http://wso2.com/ >> >> Mobile : +94 712383306 >> >> _______________________________________________ >> Architecture mailing list >> architect...@wso2.org >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> >> > > > -- > > *Sanjeewa Malalgoda* > WSO2 Inc. > Mobile : +94713068779 > > <http://sanjeewamalalgoda.blogspot.com/>blog > :http://sanjeewamalalgoda.blogspot.com/ > <http://sanjeewamalalgoda.blogspot.com/> > > > > _______________________________________________ > Dev mailing list > Dev@wso2.org > http://wso2.org/cgi-bin/mailman/listinfo/dev > > -- Chamin Dias *Software Engineer* Mobile : +94 (0) 716 097455 <%2B94%20%280%29%20773%20451194> Email : cham...@wso2.com Blog : https://chamindias.wordpress.com/
_______________________________________________ Dev mailing list Dev@wso2.org http://wso2.org/cgi-bin/mailman/listinfo/dev
