Topics

Swagger or RAML

Drasko DRASKOVIC <drasko@...>
 

Related to this: https://github.com/drasko/edgex-export/issues/21

I would like to hear community opinion, especially that Linux
foundation's Open API Initiative (https://www.openapis.org/) seems to
be aligned around Swagger.

Best regards,
Drasko DRASKOVIC
Mainflux Author and Technical Advisor

www.mainflux.com | Industrial IoT Cloud
-------------------------------------------------------------------
Engineering Division | Paris, France

LinkedIn: https://www.linkedin.com/in/draskodraskovic
Twitter: @draskodraskovic

James.White2@...
 

Drasko,
we looked at both while developing Fuse. Cloud Tsai from our team did a great job of looking at them both (and others). Tooling, at the time, provided the slight edge to RAML.

My feeling has been that someday, it would be nice to have API documentation in both RAML and Swagger (or even other formats if they have a significant following) - especially if we can get it to the point where that documentation is automatically generated from the code artifacts. The issue right now is that it still requires a fair amount of work (mostly manual work as the tooling we have found is not all the way there yet) to care, feed and maintain any of these document sets. The tooling we have in place to generate the RAML is far from perfect, but at least as of last year, it beat out what we found for Swagger.

The user community may have a preference, but we didn't see a strong enough pull to one or the other to trump our selection based on ease to create and make available the API documentation.

If you or anyone in the community would like to contribute and maintain the Swagger docs, improve automatic generation of either RAML or Swagger API documentation, or otherwise provide a better facilitate the sharing of the micro service APIs with the world, we would be extremely welcoming and grateful. Please consider making a contribution to make it so :)

________________________________________
From: edgex-golang-bounces@... <edgex-golang-bounces@...> on behalf of Drasko DRASKOVIC <drasko@...>
Sent: Thursday, October 19, 2017 2:07 PM
To: edgex-devel@...; edgex-golang@...; edgex-tsc@...; Dejan Mijic; Nikola Marcetic
Subject: [Edgex-golang] Swagger or RAML

Related to this: https://github.com/drasko/edgex-export/issues/21

I would like to hear community opinion, especially that Linux
foundation's Open API Initiative (https://www.openapis.org/) seems to
be aligned around Swagger.

Best regards,
Drasko DRASKOVIC
Mainflux Author and Technical Advisor

www.mainflux.com | Industrial IoT Cloud
-------------------------------------------------------------------
Engineering Division | Paris, France

LinkedIn: https://www.linkedin.com/in/draskodraskovic
Twitter: @draskodraskovic

_______________________________________________
EdgeX-GoLang mailing list
EdgeX-GoLang@...
https://lists.edgexfoundry.org/mailman/listinfo/edgex-golang

Cates, Sol
 

We have started to standardize on OpenAPI as our spec, and have found go-swagger to be the best way to leverage it in GoLang, as the scaffolding for a client or server implementation is as simple as a simple 1 line command to generate. Then our devs have less stack to maintain or develop, and just have to focus on the business logic of the API.

We also liked RAML, but for the pattern of microservices written in GoLang, go-swagger had a lead from our perspective.



Sol Cates
VP of Technology Strategy, CTO Office
Tel: +1 (503) 756 1410
Email: scates@...
Twitter: @solcates

On 10/19/17, 12:30 PM, "edgex-golang-bounces@... on behalf of James.White2@..." <edgex-golang-bounces@... on behalf of James.White2@...> wrote:

Drasko,
we looked at both while developing Fuse. Cloud Tsai from our team did a great job of looking at them both (and others). Tooling, at the time, provided the slight edge to RAML.

My feeling has been that someday, it would be nice to have API documentation in both RAML and Swagger (or even other formats if they have a significant following) - especially if we can get it to the point where that documentation is automatically generated from the code artifacts. The issue right now is that it still requires a fair amount of work (mostly manual work as the tooling we have found is not all the way there yet) to care, feed and maintain any of these document sets. The tooling we have in place to generate the RAML is far from perfect, but at least as of last year, it beat out what we found for Swagger.

The user community may have a preference, but we didn't see a strong enough pull to one or the other to trump our selection based on ease to create and make available the API documentation.

If you or anyone in the community would like to contribute and maintain the Swagger docs, improve automatic generation of either RAML or Swagger API documentation, or otherwise provide a better facilitate the sharing of the micro service APIs with the world, we would be extremely welcoming and grateful. Please consider making a contribution to make it so :)

________________________________________
From: edgex-golang-bounces@... <edgex-golang-bounces@...> on behalf of Drasko DRASKOVIC <drasko@...>
Sent: Thursday, October 19, 2017 2:07 PM
To: edgex-devel@...; edgex-golang@...; edgex-tsc@...; Dejan Mijic; Nikola Marcetic
Subject: [Edgex-golang] Swagger or RAML

Related to this: https://github.com/drasko/edgex-export/issues/21

I would like to hear community opinion, especially that Linux
foundation's Open API Initiative (https://www.openapis.org/) seems to
be aligned around Swagger.

Best regards,
Drasko DRASKOVIC
Mainflux Author and Technical Advisor

www.mainflux.com | Industrial IoT Cloud
-------------------------------------------------------------------
Engineering Division | Paris, France

LinkedIn: https://www.linkedin.com/in/draskodraskovic
Twitter: @draskodraskovic

_______________________________________________
EdgeX-GoLang mailing list
EdgeX-GoLang@...
https://lists.edgexfoundry.org/mailman/listinfo/edgex-golang
_______________________________________________
EdgeX-GoLang mailing list
EdgeX-GoLang@...
https://lists.edgexfoundry.org/mailman/listinfo/edgex-golang

James.White2@...
 

It is important for everyone to remember that EdgeX is a polyglot platform. So while one tool, architecture, design selection, etc may work best for one language, we need to consider the impact to the others as well. This is not to say that we won't have to make some tough choices and in some cases do things because it is easier to do in the more widely used language. But where possible, keep in mind that just because it works well in Go isn't necessarily a solution that works for everyone as well.

In the case of API documentation - the whole purpose is to be as platform/language independent as possible so that any user of EdgeX in any language can still call the microservices.

________________________________________
From: Cates, Sol <scates@...>
Sent: Thursday, October 19, 2017 2:45 PM
To: White2, James; drasko@...; edgex-devel@...; edgex-golang@...; edgex-tsc@...; dejan.mjc@...; nikola@...
Subject: Re: [Edgex-golang] Swagger or RAML

We have started to standardize on OpenAPI as our spec, and have found go-swagger to be the best way to leverage it in GoLang, as the scaffolding for a client or server implementation is as simple as a simple 1 line command to generate. Then our devs have less stack to maintain or develop, and just have to focus on the business logic of the API.

We also liked RAML, but for the pattern of microservices written in GoLang, go-swagger had a lead from our perspective.



Sol Cates
VP of Technology Strategy, CTO Office
Tel: +1 (503) 756 1410
Email: scates@...
Twitter: @solcates












On 10/19/17, 12:30 PM, "edgex-golang-bounces@... on behalf of James.White2@..." <edgex-golang-bounces@... on behalf of James.White2@...> wrote:

Drasko,
we looked at both while developing Fuse. Cloud Tsai from our team did a great job of looking at them both (and others). Tooling, at the time, provided the slight edge to RAML.

My feeling has been that someday, it would be nice to have API documentation in both RAML and Swagger (or even other formats if they have a significant following) - especially if we can get it to the point where that documentation is automatically generated from the code artifacts. The issue right now is that it still requires a fair amount of work (mostly manual work as the tooling we have found is not all the way there yet) to care, feed and maintain any of these document sets. The tooling we have in place to generate the RAML is far from perfect, but at least as of last year, it beat out what we found for Swagger.

The user community may have a preference, but we didn't see a strong enough pull to one or the other to trump our selection based on ease to create and make available the API documentation.

If you or anyone in the community would like to contribute and maintain the Swagger docs, improve automatic generation of either RAML or Swagger API documentation, or otherwise provide a better facilitate the sharing of the micro service APIs with the world, we would be extremely welcoming and grateful. Please consider making a contribution to make it so :)

________________________________________
From: edgex-golang-bounces@... <edgex-golang-bounces@...> on behalf of Drasko DRASKOVIC <drasko@...>
Sent: Thursday, October 19, 2017 2:07 PM
To: edgex-devel@...; edgex-golang@...; edgex-tsc@...; Dejan Mijic; Nikola Marcetic
Subject: [Edgex-golang] Swagger or RAML

Related to this: https://github.com/drasko/edgex-export/issues/21

I would like to hear community opinion, especially that Linux
foundation's Open API Initiative (https://www.openapis.org/) seems to
be aligned around Swagger.

Best regards,
Drasko DRASKOVIC
Mainflux Author and Technical Advisor

www.mainflux.com | Industrial IoT Cloud
-------------------------------------------------------------------
Engineering Division | Paris, France

LinkedIn: https://www.linkedin.com/in/draskodraskovic
Twitter: @draskodraskovic

_______________________________________________
EdgeX-GoLang mailing list
EdgeX-GoLang@...
https://lists.edgexfoundry.org/mailman/listinfo/edgex-golang
_______________________________________________
EdgeX-GoLang mailing list
EdgeX-GoLang@...
https://lists.edgexfoundry.org/mailman/listinfo/edgex-golang

Drasko DRASKOVIC <drasko@...>
 

Hi Jim,

On Thu, Oct 19, 2017 at 9:30 PM, <James.White2@...> wrote:
Drasko,
we looked at both while developing Fuse. Cloud Tsai from our team did a great job of looking at them both (and others). Tooling, at the time, provided the slight edge to RAML.

My feeling has been that someday, it would be nice to have API documentation in both RAML and Swagger (or even other formats if they have a significant following) - especially if we can get it to the point where that documentation is automatically generated from the code artifacts. The issue right now is that it still requires a fair amount of work (mostly manual work as the tooling we have found is not all the way there yet) to care, feed and maintain any of these document sets. The tooling we have in place to generate the RAML is far from perfect, but at least as of last year, it beat out what we found for Swagger.

The user community may have a preference, but we didn't see a strong enough pull to one or the other to trump our selection based on ease to create and make available the API documentation.

If you or anyone in the community would like to contribute and maintain the Swagger docs, improve automatic generation of either RAML or Swagger API documentation, or otherwise provide a better facilitate the sharing of the micro service APIs with the world, we would be extremely welcoming and grateful. Please consider making a contribution to make it so :)
Sure, this is why I opened the issue here:
https://github.com/drasko/edgex-export/issues/21. These issues are
task list (and a reminder for me), i.e. what i plan to contribute in
the repo. API server would be incomplete without documentation :).

I just wanted to check with you and community Swagger or RAML, as I
have no particular preferences - I gave a short opinion (and what I've
seen around so far), but they are interchangeable via tools anyway.

Best regards,
Mainflux Author and Technical Advisor

www.mainflux.com | Industrial IoT Cloud
-------------------------------------------------------------------
Engineering Division | Paris, France

LinkedIn: https://www.linkedin.com/in/draskodraskovic
Twitter: @draskodraskovic