Happy to go with (1) for now. Thanks Seb
Sebastian Wagner Director Arrakeen Solutions, OM-Hosting.com http://arrakeen-solutions.co.nz/ https://om-hosting.com - Cloud & Server Hosting for HTML5 Video-Conferencing OpenMeetings <https://www.youracclaim.com/badges/da4e8828-743d-4968-af6f-49033f10d60a/public_url> <https://www.youracclaim.com/badges/b7e709c6-aa87-4b02-9faf-099038475e36/public_url> On Thu, 2 Sept 2021 at 16:22, seba.wag...@gmail.com <seba.wag...@gmail.com> wrote: > Swagger is for Rest API Documentation for e.g what is the API Signature > Inputs and Outputs. > Please read > https://swagger.io/resources/articles/documenting-apis-with-swagger/ for > further information on Swagger > > Especially for API and Front End developers would prefer a Swagger doc. If > you look at: > > https://editor.swagger.io/?url=https://openmeetings.apache.org/swagger/appache-openmeetings-7.0.0-SNAPSHOT-swagger.json > > The swagger gives you: > > - Design-first users: use Swagger Codegen > <https://swagger.io/swagger-codegen/> to generate a server stub for > your API. The only thing left is to implement the server logic – and your > API is ready to go live! > - Use Swagger Codegen <https://swagger.io/swagger-codegen/> to generate > client libraries for your API in over 40 languages. > - Use Swagger UI <https://swagger.io/swagger-ui/> to generate interactive > API documentation that lets your users try out the API calls directly > in the browser. > - Use the spec to connect API-related tools to your API. For example, > import the spec to SoapUI <https://soapui.org/> to create automated > tests for your API. > > Most developers expect a Rest API these days as opposed to a Soap API. You > can also see that in the adoption of new tools and libraries. > > And swagger seems to have established itself as the de facto standard for > documenting Rest APIs. > > Thanks, > Seb > > Sebastian Wagner > Director Arrakeen Solutions, OM-Hosting.com > http://arrakeen-solutions.co.nz/ > https://om-hosting.com - Cloud & Server Hosting for HTML5 > Video-Conferencing OpenMeetings > > <https://www.youracclaim.com/badges/da4e8828-743d-4968-af6f-49033f10d60a/public_url> > <https://www.youracclaim.com/badges/b7e709c6-aa87-4b02-9faf-099038475e36/public_url> > > > On Thu, 2 Sept 2021 at 14:55, Ali Alhaidary <ali.alhaid...@the5stars.org> > wrote: > >> I second you @max. >> >> Ali >> >> On 9/2/21 5:47 AM, Maxim Solodovnik wrote: >> > I would vote to have swagger at >> https://openmeetings.apache.org/swagger/ >> > only >> > I see no benefit in shipping it with every build >> > >> > we can add some instructions to docs on how to add personal UI >> > >> > I'm still not sure how swagger can help, and why it is better than >> javadoc >> > :) >> > >> > On Thu, 2 Sept 2021 at 04:25, seba.wag...@gmail.com < >> seba.wag...@gmail.com> >> > wrote: >> > >> >> Hi, >> >> >> >> as for the generated swagger API definition, there are a few options >> on how >> >> to ship it with every distribution of OpenMeetings: >> >> >> >> 1) Just include the raw openapi json and yaml file. If somebody wants >> to >> >> browse the spec they have to use their own swagger editor. >> >> 2) Include the swagger-ui in each distribution so that the openapi >> json and >> >> yaml are browsable same as https://openmeetings.apache.org/swagger/ >> (would >> >> become something like http://localhost:5080/openmeetings/swagger) on >> each >> >> local machine >> >> >> >> (2) is more neat and what most projects do. >> >> >> >> However with (2) there are a few challenges: >> >> A) The swagger UI is ~5MB in HTML/JS/CSS. We can include it but it >> will add >> >> to the distribution zip/tar.gz file. It will be probably much less >> (~1MB) >> >> once its zipped up. >> >> B) I will need to write some sort of task that pulls the latest >> version of >> >> the swagger UI from github or NPM (otherwise I would need to check in >> the >> >> UI artifacts into our repo, which makes our repository slower and >> larger) >> >> C) We need to be able to disable the access to the swagger UI URL. In >> >> production environments people shouldn't expose the API docs publicly >> >> >> >> We can do (2), I just want to make sure we understand A, B, C. Cause >> that >> >> will be a few changes to add. >> >> >> >> Thanks, >> >> Sebastian >> >> >> >> Sebastian Wagner >> >> Director Arrakeen Solutions, OM-Hosting.com >> >> http://arrakeen-solutions.co.nz/ >> >> https://om-hosting.com - Cloud & Server Hosting for HTML5 >> >> Video-Conferencing OpenMeetings >> >> < >> >> >> https://www.youracclaim.com/badges/da4e8828-743d-4968-af6f-49033f10d60a/public_url >> >> < >> >> >> https://www.youracclaim.com/badges/b7e709c6-aa87-4b02-9faf-099038475e36/public_url >> > >> >
