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 <[email protected]> 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, [email protected] < > [email protected]> > > 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 > > >
