Started to update Guillotina_swagger which is an addon to Guillotina, generates swagger UI for Guillotina, link to last week blog.

Things which were completed:- PR:- Upgrade swagger #3

• Updated static js and css for OpenAPI 3. Issue#506
• Updated swaggerObject(which is not OpenAPI object) according to OpenAPI 3 specifications. Issue#505

 What did you do this week?:- Issue#513 

Guillotina_swagger need authentication in order to generate the swagger object with the path object a user is authorized to access. Previously HTTP basic auth or JWT token were manually added to all the request headers and then the response object was rendered by swaggerUI which is now replaced by `securitySchemes` of OpenAPI 3. Instead of adding auth token to request header manually now `securitySchemes` of OpenAPI 3.

Definition of path objects is defined inline in the guillotina repository along with every endpoint. In OpenAPI 3  schema, parameters, responses, and definitions are now a part on a new object which is component, it's is one of the major changes required for the upgrade. 

What is coming up next?

Path Object is created by Guillotina_swagger according to the permissions a user have, previously it was done by sending auth token to the baseurl. Now all the authentication is taken care by swaggerUI auth except the request send to get the OpenAPI object, which requires a fix.

Did you get stuck anywhere?

 OpenAPI's authentication adds auth token to the request created to all the endpoints but the requests send to baseurl also need to have the auth token in order to generate the proper path object, it can be added manually to the request header but that would be a hacky solution. This problem still needs some research and brainstorming. 

Issue #505

Guillotina_swagger is a addon to Guillotina which generates Swagger interface for the endpoints defined in Guillotina according to user access.

Task- Is to upgrade the Swagger object generated by Guillotina_swagger according to OpenAPI3 specs.

Terms which will be used in the article:-

Swagger/OpenAPI: Swagger is an open source framework used for documenting and testing APIs which has now upgraded to OpenAPI3

SwaggerUI: SwaggerUI is a tool provided by Swagger to generate a UI where all the functionalities of an API can be documented and tested.

Swagger Object/OpenAPI Object: Swagger Object is JSON or YAML where specifications about APIs are defined. 

Guillotina_swagger generates swagger object(which is OpenAPI now) which is consumed by the frontend to create swaggerUI. 

Changes required:- 

• Upgrading previously used swaggerUI packages(js,css files).
• Upgrading Swagger Object according to new OpenAPI Specification.
• Updating Javascript which is used to render swagger Object on the frontend

What did you do this week?

Started from understanding Guillotina and Guillotina_swagger and the things which need to be upgraded for OpenAPI3. Upgraded previously used SwaggerUI packages. Updated Swagger Object generated by Guillotina_swagger according to OpenAPI 3 specifications. Major changes which happened due to shift on OpenAPI 3 are - 

• swagger.host, swagger.basepath, swagger.schemes now comes under a new object swagger.servers
• securityDefinitions, produces, consumes, definitions, parameter, responses comes under component which is also a new object in OpenAPI 3.

What is coming up next week? 

• Previously authentication was managed manually by adding authentication tokens inside the request created to get swagger object, this will be changed by using inbuilt securityDefinitions of SwaggerUI.
• Schema, parameters, definitions, and responses are defined inside guillotina which are used inside path object of are needed to be updated as schema, parameters, definitions and responses are now a part of component object.

Hello Everyone, It's Karan Pratap Singh an undergraduate student from India. I got selected in GSOC'19 project(Plone: Guillotina API Evolution) under Plone which is a sub-org of Python Software Foundation. I will be working on a major upgradation of Guillotina which is a fullstack Async framework for the next 12 weeks. My project involves 

• Upgrading Swagger2.0 documentation of the apis to Openapi 3.
• Validating JSON schema to all the request and responses.
• Working on adding all api's functionalities to the websocket endpoint to Guillotina.
• Adding a mechanism to version the API.
• And adding helm chart for easy deployment of Guillotina

I will be writing weekly blogs for the next 12 weeks explaining my work and progress.

Thank you for reading