There are several problems in allowing to edit the Swagger file directly. 1. We change it on new product releases. So now users have to find a way to merge whatever their changes when doing product upgrades. This is error prone.
2. The Swagger file is 100s of lines long and it has lots of content the sys-admin doesn't really need to know/understand in order to change the resource to scope mapping. So its too hard for him to configure it. Plus, I think its too risky. Ex: if he accidentally removes a path param, the generated code and swagger will be out of sync and result in weird errors. 3. If we provide WUM updates to the Swagger file (for new features or bug fixes), the sys-admin needs to sync up the Swagger file on each update that has a change in the Swagger file. 4. We have to marry the sys-admin with Swagger-2.0. When we upgrade to OAS 3.0, we have to expect the sys-admin to now know the syntax of OAS 3.0. Its better if we just make him aware of REST. On Tue, May 9, 2017 at 11:20 AM, Sanjeewa Malalgoda <sanje...@wso2.com> wrote: > IMO its more like keep different representation of same data in different > location. To edit/update optional place you suggested user anyway need to > refer swagger file. So why don't we simply let users to edit it self > without having another file? > > Thanks, > sanjeewa. > > On Tue, May 9, 2017 at 11:01 AM, Nuwan Dias <nuw...@wso2.com> wrote: > >> >> >> On Tue, May 9, 2017 at 10:46 AM, Sanjeewa Malalgoda <sanje...@wso2.com> >> wrote: >> >>> >>> >>> On Tue, May 9, 2017 at 10:15 AM, Nuwan Dias <nuw...@wso2.com> wrote: >>> >>>> @Sanjeewa, if someone edits the Swagger file in conf, how do we ensure >>>> the next restart doesn't override that file? >>>> >>> If file exists it will not override else it will write to file system. >>> If its containerized automated deployment then automation process need to >>> copy file. >>> >>>> >>>> The root cause of the problem here is that the "resource to scope" >>>> mapping is both a server configuration as well as it might be a user >>>> configuration when users want to find/corse grain the permissions of the >>>> API. >>>> >>> I think this is server configuration and not a user configuration. We >>> should not users to edit this randomly. This mapping need to determine by >>> system administrator by the time deployment initialize and should update >>> only when required. Ex if you allow to update some resource to given role >>> and randomly revoke that its not nice. >>> >> >> Yes, by "user" I actually meant sys-admin. The guy configuring the server >> actually. >> >>> >>>> What if we allow the default resource to scope mapping remain in the >>>> Swagger doc and introduce a new config file to override whatever resource >>>> to scope mappings a user needs? To determine the scope of a particular >>>> resource our code should first be checking the custom/optional config file >>>> and if an entry for the particular resource doesn't exist, then default to >>>> the Swagger file. >>>> >>> Having more config files will make things complicate IMO. >>> >> >> If we copy the Swagger to the conf directory, that becomes a duplicate >> config file anyway (one in the jar and one outside the jar). And when we do >> that we grant full access to the sys-admin to play with the product rest >> API (the full Swagger doc). Which is not needed. What he only needs is to >> override the resource to scope mapping. Which I think should be possible to >> provide by having a optional place to override whatever mapping he needs >> only. >> >> We also need to think about product upgrades. If the sys admin edits the >> swagger of one version and then upgrades the server, he'll be expected to >> merge whatever his changes with the newer swagger doc of the product. Which >> can be troublesome. But if we use an optional config that only overrides >> whatever resources he wants, he can simply use the same file on the new >> version of the product. >> >>> >>> Thanks, >>> sanjeewa. >>> >>>> >>>> This way the optional config file only needs to bear the resource to >>>> scope mappings that need to be overridden in a particular deployment and >>>> hence won't be that long. It also ensures that during product upgrades >>>> users don't have to meddle with the current config file and can keep using >>>> it on newer versions too. >>>> >>>> Thanks, >>>> NuwanD. >>>> >>>> On Mon, May 8, 2017 at 11:46 PM, Sanjeewa Malalgoda <sanje...@wso2.com> >>>> wrote: >>>> >>>>> >>>>> >>>>> On Mon, May 8, 2017 at 3:42 PM, Ishara Cooray <isha...@wso2.com> >>>>> wrote: >>>>> >>>>>> >>>>>> >>>>>> *Motivation:* >>>>>> Before c5, API Manager product REST APIs resources have pre defined >>>>>> scopes and they cannot be changed. >>>>>> >>>>>> But what if an admin needs to give access to Create, Update, Delete >>>>>> actions to different users? >>>>>> if he can customize the scopes associated with each resource, then he >>>>>> will be able to fine grain the access to each resource. >>>>>> >>>>>> >>>>>> >>>>>> *Design:*With C5, we thought of allowing admin users to add/change >>>>>> scopes in product REST APIs to meet their fine grained requirements. >>>>>> >>>>>> At the moment we can think of two ways to do this. >>>>>> >>>>>> 1. *Allow to edit the scopes defined per resource * >>>>>> In this case we can copy the swagger file into conf directory at >>>>>> build time, so that it can be maintained as a usual configuration >>>>>> file. >>>>>> >>>>>> When server startup we can copy these swagger files to conf directory >>>>> and refer it from there. Maintain separate file for mapping make things >>>>> more complex IMO. >>>>> Lets follow this for all swagger based APIs. >>>>> >>>>> Thanks, >>>>> sanjeewa. >>>>> >>>>>> >>>>>> 1. >>>>>> 2. *Introduce a new config file to track resource to scope mapping.* >>>>>> In this case the issue is resource to scope mapping will be >>>>>> duplicated. >>>>>> >>>>>> Appreciate your insight on this. >>>>>> >>>>>> >>>>>> Thanks & Regards, >>>>>> Ishara Cooray >>>>>> Senior Software Engineer >>>>>> Mobile : +9477 262 9512 <+94%2077%20262%209512> >>>>>> WSO2, Inc. | http://wso2.com/ >>>>>> Lean . Enterprise . Middleware >>>>>> >>>>> >>>>> >>>>> >>>>> -- >>>>> >>>>> *Sanjeewa Malalgoda* >>>>> WSO2 Inc. >>>>> Mobile : +94713068779 <+94%2071%20306%208779> >>>>> >>>>> <http://sanjeewamalalgoda.blogspot.com/>blog >>>>> :http://sanjeewamalalgoda.blogspot.com/ >>>>> <http://sanjeewamalalgoda.blogspot.com/> >>>>> >>>>> >>>>> >>>> >>>> >>>> -- >>>> Nuwan Dias >>>> >>>> Software Architect - WSO2, Inc. http://wso2.com >>>> email : nuw...@wso2.com >>>> Phone : +94 777 775 729 <077%20777%205729> >>>> >>> >>> >>> >>> -- >>> >>> *Sanjeewa Malalgoda* >>> WSO2 Inc. >>> Mobile : +94713068779 <+94%2071%20306%208779> >>> >>> <http://sanjeewamalalgoda.blogspot.com/>blog >>> :http://sanjeewamalalgoda.blogspot.com/ >>> <http://sanjeewamalalgoda.blogspot.com/> >>> >>> >>> >> >> >> -- >> Nuwan Dias >> >> Software Architect - WSO2, Inc. http://wso2.com >> email : nuw...@wso2.com >> Phone : +94 777 775 729 <077%20777%205729> >> > > > > -- > > *Sanjeewa Malalgoda* > WSO2 Inc. > Mobile : +94713068779 <+94%2071%20306%208779> > > <http://sanjeewamalalgoda.blogspot.com/>blog :http://sanjeewamalalgoda. > blogspot.com/ <http://sanjeewamalalgoda.blogspot.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
