You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@openmeetings.apache.org by "seba.wagner@gmail.com" <se...@gmail.com> on 2021/09/01 21:25:16 UTC
Options for shipping swagger API definition with OpenMeetings
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>
Re: Options for shipping swagger API definition with OpenMeetings
Posted by "seba.wagner@gmail.com" <se...@gmail.com>.
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.wagner@gmail.com <se...@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 <al...@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.wagner@gmail.com <
>> seba.wagner@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
>> >
>>
>
Re: Options for shipping swagger API definition with OpenMeetings
Posted by Maxim Solodovnik <so...@gmail.com>.
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, seba.wagner@gmail.com <se...@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.
>
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 <al...@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.wagner@gmail.com <
> > seba.wagner@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
> > >
> >
>
--
Best regards,
Maxim
Re: Options for shipping swagger API definition with OpenMeetings
Posted by "seba.wagner@gmail.com" <se...@gmail.com>.
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 <al...@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.wagner@gmail.com <
> seba.wagner@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
> >
>
Re: Options for shipping swagger API definition with OpenMeetings
Posted by Ali Alhaidary <al...@the5stars.org>.
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.wagner@gmail.com <se...@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
>
Re: Options for shipping swagger API definition with OpenMeetings
Posted by Maxim Solodovnik <so...@gmail.com>.
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.wagner@gmail.com <se...@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
> >
>
--
Best regards,
Maxim