My concern is on the folks who aren’t even aware of the oas version being used. When someone is creating an api on the UI, they’ll feel as if the SDK generation has vanished (if we disable it for v3 ones). Therefore it’ll be better to make v2 the default and provide a warning on the UI regarding SDKs when switching to 3.0.
On Thu, 25 Jan 2018 at 11:46 am, Thilini Shanika <thili...@wso2.com> wrote: > If someone creates an API from the UI, the default swagger doc will be in > version 3 right? Can a developer switch back to a 2.0 based definition if > so? > > As per the current implementation, the default version of the generation > swagger doc is a version 3.0.0 supported doc. But the publisher user can > selectively decide the supported swagger version, in the advanced option > provided at starting point of API creation. > > Initially, we tried to provide the functionality of switching the API spec > version in API design phase but then we faced some difficulties to handle > the swagger doc conversion of 2.0 -> 3.0.0 and 3.0.0 -> 2.0 and we could > not find any third party library to handle this conversion. We can write a > conversion for the basic swagger definition we generate underneath, but in > a case where the user edits the swagger doc via the swagger editor, and > adds some complex definitions to api doc, then we need to consider them as > handle those complex definition conversions too. > > Further, we tried to maintain two swagger definition objects for OAS 3.0 > and Swagger 2.0.0, and as we perform different operations via API design > phase, both objects will be updated as per the operation (ie: Adding new > resource, parameters). Once the user switched the swagger version, the > requested swagger definition will be loaded as the API's swagger doc. But > that was not a clean way of handling the conversion so that we decided to > stick to the current approach of specifying the swagger definition at api > create staring point. > > > > [image: Inline image 1] > > > > On Thu, Jan 25, 2018 at 11:07 AM, Nuwan Dias <nuw...@wso2.com> wrote: > >> If someone creates an API from the UI, the default swagger doc will be in >> version 3 right? Can a developer switch back to a 2.0 based definition if >> so? >> >> On Thu, 25 Jan 2018 at 9:45 am, Thilini Shanika <thili...@wso2.com> >> wrote: >> >>> Hi All, >>> >>> We have been supporting client side SDK generation via API Store and API >>> Store REST APIs, for swagger 2.0 based definitions. But currently, we are >>> unable to support this particular feature fo OAS 3 based APIs, since the >>> swagger codegen 3.x version, which is having OAS 3.0.0 support, is not >>> released yet. >>> >>> Thus, shall we disable this functionality for OAS 3 specific APIs? >>> Basically, we should disable the SDK generation via API Store and REST >>> APIs, if it is an OAS 3.0.0 based API. >>> >>> WDYT? >>> >>> >>> On Wed, Jan 10, 2018 at 10:54 AM, Thilini Shanika <thili...@wso2.com> >>> wrote: >>> >>>> @Harsha >>>> >>>> In this case will our swagger console in store compatible with multiple >>>> swagger versions? How would be the compatibility of swagger library across >>>> multiple versions that we currently used in the product? >>>> >>>> Yes, it is compatible. We have upgraded Swagger UI to 3.x version, >>>> which is having support for both Swagger 2.0 and Open API 3.0. Basically, >>>> the current swagger ui embedded in APIM supports both versions, but we need >>>> to carefully handle the custom elements that we inject to swagger >>>> definition before rendering it to API Store ie: gateway environment >>>> details, security definitions etc (There are differences of specifying API >>>> endpoints and security definitions Swagger 2.0 and Open API 3.0) >>>> >>>> >>>> @Roshan >>>> >>>> >>>> Do we have a significant difference between swagger and openAPI? >>>> According to the >>>> https://swagger.io/blog/difference-between-swagger-and-openapi/, >>>> swagger is a tool and openAPI is the spec it self. >>>> >>>> Yes, there are some significant differences between Swagger 2.0 and >>>> Open API 3.0 spec. Please refer to [1] to have an overview understanding on >>>> whats net in Open API 3.0. Basically swagger spec has been renamed as >>>> OpenAPI as it was donated to Linux foundation and technically OpenAPI 3.0 >>>> is the Swagger spec version 3.0. But still, openAPI uses the swagger tools >>>> ie: Swagger UI, Swagger Editor, Swagger codegen >>>> >>>> Do we need to concern about swagger definition vs openAPI definition, >>>> rather versions of it? >>>> Since OpenAPI 3.0 has to be considered as the Swagger 3.0, we need to >>>> consider the version. >>>> >>>> [1] https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/ >>>> >>>> On Wed, Jan 10, 2018 at 4:55 AM, roshan wijesena <roshan86...@gmail.com >>>> > wrote: >>>> >>>>> Folks, >>>>> >>>>> Do we have a significant difference between swagger and openAPI? >>>>> According to the >>>>> https://swagger.io/blog/difference-between-swagger-and-openapi/, >>>>> swagger is a tool and openAPI is the spec it self. >>>>> >>>>> Do we need to concern about swagger definition vs openAPI definition, >>>>> rather versions of it? >>>>> >>>>> Regards >>>>> Roshan >>>>> >>>>> >>>>> >>>>> On Wed, Jan 10, 2018 at 7:25 AM, Harsha Kumara <hars...@wso2.com> >>>>> wrote: >>>>> >>>>>> >>>>>> >>>>>> On Tue, Jan 9, 2018 at 10:57 AM, Thilini Shanika <thili...@wso2.com> >>>>>> wrote: >>>>>> >>>>>>> @Bhathiya, >>>>>>> >>>>>>> Our initial plan was to provide an advanced option for developers to >>>>>>> decide the version(Whether in Swagger 2.0 or OpenAPI 3.0) of the >>>>>>> generating swagger definition, but later we decided to stick to OpenAPI >>>>>>> 3.0 >>>>>>> for newly creating APIs to avoid some complexities in supporting both >>>>>>> versions for APIs which are created from scratch in API Publisher. We >>>>>>> would >>>>>>> further check the feasibility and alternative solutions of supporting >>>>>>> both >>>>>>> versions in API Design phase. >>>>>>> >>>>>>> @Chamila >>>>>>> Thanks for bringing this up for discussion. Yes, we are planning to >>>>>>> support both swagger versions in REST APIs like API create, API update, >>>>>>> API >>>>>>> Definition Update etc. >>>>>>> >>>>>> In this case will our swagger console in store compatible with >>>>>> multiple swagger versions? How would be the compatibility of swagger >>>>>> library across multiple versions that we currently used in the product? >>>>>> >>>>>>> >>>>>>> @Lakmal >>>>>>> I moved the summery of the conversation to [1] and we can continue >>>>>>> the rest of the discussion in the GitHub issue itself. >>>>>>> >>>>>>> On Tue, Jan 9, 2018 at 9:37 AM, Lakmal Warusawithana < >>>>>>> lak...@wso2.com> wrote: >>>>>>> >>>>>>>> Hi Thilini, >>>>>>>> >>>>>>>> Shall we add this discussion into issue [1] itself. It will be >>>>>>>> easy to external party to get involve. >>>>>>>> >>>>>>>> On Mon, Jan 8, 2018 at 2:28 PM, Thilini Shanika <thili...@wso2.com> >>>>>>>> wrote: >>>>>>>> >>>>>>>>> Hi All, >>>>>>>>> >>>>>>>>> We are planning to provide OpenAPI 3.0 specification support for >>>>>>>>> API Manager 2.2.0 [1]. We did a background research on what's new in >>>>>>>>> OpenAPI and the feasibility of providing OpenAPI 3.0 support over APIM >>>>>>>>> 2.2.0. As per the current architecture of APIM, it is feasible to >>>>>>>>> support >>>>>>>>> OpenAPI 3.0 spec, parallel with Swagger 2.0 (Swagger 2.0 support is >>>>>>>>> required for migrated APIs from previous releases) >>>>>>>>> >>>>>>>>> Following are the functionalities we are planning to ship with >>>>>>>>> this new feature. >>>>>>>>> >>>>>>>>> 1. Supporting OpenAPI 3.0 spec for newly designing/Creating >>>>>>>>> APIs (When an API is created from the scratch, the underneath API >>>>>>>>> definition will be generated in OpenAPI 3.0) >>>>>>>>> 2. The API definitions of migrated APIs from previous releases >>>>>>>>> are based on Swagger 2.0 spec. Thus, Swagger 2.0 spec support will >>>>>>>>> be >>>>>>>>> continued for migrated APIs >>>>>>>>> 3. Providing support to import OpenAPI 3.0 spec based API >>>>>>>>> definitions while creating an API from an existing source. >>>>>>>>> 4. Swagger editor in APIM 2.2.0 has been upgraded to 3.x >>>>>>>>> version so that it will be supporting OpenAPI 3.0 spec while >>>>>>>>> updating API >>>>>>>>> source via Swagger Editor in API Publisher. >>>>>>>>> 5. Swagger UI in APIM 2.2.0 has been upgraded to 3.x version >>>>>>>>> so that API Console in API Store will be supporting OpenAPI 3.0 >>>>>>>>> based API >>>>>>>>> definitions >>>>>>>>> 6. Providing the functionality of switching the gateway >>>>>>>>> environment endpoints for OpenAPI 3.0 specific APIs (If it is a >>>>>>>>> Swagger 2.0 >>>>>>>>> based API definition, the relevant gateway endpoint should be >>>>>>>>> specified in >>>>>>>>> host, basepath and schema elements of the Swagger definition. But >>>>>>>>> in >>>>>>>>> OpenAPI 3.0, the gateway endpoint details should be specified >>>>>>>>> under server >>>>>>>>> element of the definition. ) >>>>>>>>> >>>>>>>>> >>>>>>>>> Any suggestions to improve the functionalities and usability >>>>>>>>> aspects of the feature? Your comments and thoughts on this are highly >>>>>>>>> appreciated. >>>>>>>>> >>>>>>>>> [1] https://github.com/wso2/carbon-apimgt/issues/4897 >>>>>>>>> >>>>>>>>> Thanks >>>>>>>>> >>>>>>>>> -- >>>>>>>>> Thilini Shanika >>>>>>>>> Senior Software Engineer >>>>>>>>> WSO2, Inc.; http://wso2.com >>>>>>>>> 20, Palmgrove Avenue, Colombo 3 >>>>>>>>> >>>>>>>>> E-mail: tgtshan...@gmail.com >>>>>>>>> >>>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> -- >>>>>>>> Lakmal Warusawithana >>>>>>>> Senior Director - Cloud Architecture; WSO2 Inc. >>>>>>>> Mobile : +94714289692 <+94%2071%20428%209692> >>>>>>>> Blogs : https://medium.com/@lakwarus/ >>>>>>>> http://lakmalsview.blogspot.com/ >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>> >>>>>>> >>>>>>> -- >>>>>>> Thilini Shanika >>>>>>> Senior Software Engineer >>>>>>> WSO2, Inc.; http://wso2.com >>>>>>> 20, Palmgrove Avenue, Colombo 3 >>>>>>> >>>>>>> E-mail: tgtshan...@gmail.com >>>>>>> >>>>>>> >>>>>>> _______________________________________________ >>>>>>> Architecture mailing list >>>>>>> Architecture@wso2.org >>>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>>>> >>>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> Harsha Kumara >>>>>> Software Engineer, WSO2 Inc. >>>>>> Mobile: +94775505618 <+94%2077%20550%205618> >>>>>> Blog:harshcreationz.blogspot.com >>>>>> >>>>>> _______________________________________________ >>>>>> Architecture mailing list >>>>>> Architecture@wso2.org >>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>>> >>>>>> >>>>> >>>> >>>> >>>> -- >>>> Thilini Shanika >>>> Senior Software Engineer >>>> WSO2, Inc.; http://wso2.com >>>> 20, Palmgrove Avenue, Colombo 3 >>>> >>>> E-mail: tgtshan...@gmail.com >>>> >>>> >>> >>> >>> -- >>> Thilini Shanika >>> Senior Software Engineer >>> WSO2, Inc.; http://wso2.com >>> 20, Palmgrove Avenue, Colombo 3 >>> >>> E-mail: tgtshan...@gmail.com >>> >>> -- >> Nuwan Dias >> >> Software Architect - WSO2, Inc. http://wso2.com >> email : nuw...@wso2.com >> Phone : +94 777 775 729 <+94%2077%20777%205729> >> > > > > -- > Thilini Shanika > Senior Software Engineer > WSO2, Inc.; http://wso2.com > 20, Palmgrove Avenue, Colombo 3 > > E-mail: tgtshan...@gmail.com > > -- Nuwan Dias Software Architect - WSO2, Inc. http://wso2.com email : nuw...@wso2.com Phone : +94 777 775 729
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
