Week #1 | Upgrading Guillotina_swagger

Published: 05/31/2019

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.