i use to work with swagger docs found them not very useful (personal opinion) and the UI is not very friendly (personal opinion)
let it be for those users who prefer swagger :) On Thu, 2 Sept 2021 at 11:22, [email protected] <[email protected]> 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. > SoapUI works without swagger :) > > 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 > > > > > > -- Best regards, Maxim
