Qt and OpenAPI/Swagger - a tutorial
Transcript of Qt and OpenAPI/Swagger - a tutorial
![Page 1: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/1.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 1
Qt and OpenAPI/Swagger - a tutorial
20.05.2020
![Page 2: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/2.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 2
About
20.05.2020
Marius Dege
• Working for basysKom GmbH since 2020
• Master Student at the University of Applied Sciences in Darmstadt
• Worked with Qt in my bachelor thesis
• Active contributor at the OpenAPI Generator Project
basysKom GmbH
• Located in Darmstadt and Nürnberg
• Specialized in Qt and Industrial Applications of Qt
• Measurement Applications, Manufacturing and Industrial Automation
• Customers from the DACH region
![Page 3: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/3.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 3
Outline
20.05.2020
• Motivation: What is OpenAPI and Swagger?
• OpenAPI Implementations
• Tools and Workflows
• Qt in the OpenAPI World
• Hands-On Session – Using OpenAPI Generator in a Qt-Project
• Our Contributions
• Summary
![Page 4: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/4.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 4
What is OpenAPI and Swagger?
![Page 5: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/5.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 5
• OpenAPI is a specification (OAS) of an API description format for REST APIs.
• Created to have a standard on how REST APIs are described.
• Was born out of the Swagger Project
OpenAPI
Swagger
• Allows to design, test and maintain REST APIs.
• Provides different tools.
• Client/Server code generation for over 40 languages and frameworks.
![Page 6: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/6.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 6
OpenAPI Document Example
![Page 7: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/7.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 7
Swagger vs. OpenAPI
Those terms mix up quite a bit today, so here is some historical context:
• 2011: Swagger API Project was created by Tony Tam.
• 2015: SmartBear Software created OpenAPI Initiative.
• 2016: Swagger Specification was renamed to OpenAPI Specification.
• OpenAPI Specification – the industry standard for REST API design
• Swagger – Open Source Tools work with OpenAPI documents
![Page 8: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/8.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 8
Swagger Codegen 2.0 and 3.0
Swagger has two branches for each version. Many members of the community were concerned that:
• Swagger Codegen 3.0 was diverging too much from 2.0
• There would be much maintenance overhead for two separate branches
That’s why a fork called OpenAPI Generator was founded.
![Page 9: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/9.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 9
OpenAPI Implementations
![Page 10: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/10.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 10
• The original Project
• Swagger is a set of open source tools, built around the OAS, that can help you design, document and consume REST APIs.
• https://swagger.io/
Swagger
• Forked from Swagger
• OpenAPI Generator overlaps with Swagger, only the generator was forked.
• https://openapi-generator.tech/
OpenAPI Generator
• OpenAPI (f.k.a Swagger) Specification code generator.
• https://github.com/Azure/autorest
Azure AutoRest
![Page 11: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/11.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 11
Tools and Workflows
![Page 12: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/12.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 12
• Swagger Editor
A powerful tool that allows you to test and modify your API endpoints in the browser.
• Swagger UI
Visualize OpenAPI Specification definitions in an interactive UI.
• Swagger Codegen
Generate server stubs and client SDKs from OpenAPI Specification definitions.
• OpenAPI Generator
Provided Tools from Swagger and OpenAPI Generator
![Page 13: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/13.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 13
Swagger Editor
![Page 14: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/14.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 14
Swagger UI
![Page 15: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/15.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 15
Qt in the OpenAPI World
![Page 16: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/16.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 16
What is the state of Qt support in Swagger?
• No codegen for the server side. Qt does not provide an official API for implementing HTTP servers.
• But there are generators for several c++ HTTP servers that might work for your project.
• Client codegen is supported and uses the QNetworkAccessManager.
• No codegen for OpenAPI 3.0 documents.
We found the quality to be lacking on Swagger and we encountered bugs that blocked our use-cases.
That’s why we decided to use the OpenAPI Generator for creating Qt-Clients.
We also decided to contribute for this project but more on that in the end of this talk.
Qt in the OpenAPI world
![Page 17: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/17.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 17
Hands-On Session
![Page 18: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/18.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 18
• How to use the OpenAPI Generator
• How to integrate the generated code into a Qt-Project
In this example, a hypothetical wood working machine is processing orders from an ERP system.
The ERP system is offering a REST API based on OpenAPI/Swagger.
We will show how to interface this API in a small hands-on session.
Hands-On Session – „Machine Terminal“
![Page 19: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/19.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 19
Our Contributions
![Page 20: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/20.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 20
Some details of our contributions for the OpenAPI Generator project:
• Basic authentication support
• Qt6 support by removing deprecated functions
• Better Qt documentation
Our Contributions
![Page 21: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/21.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 21
• Parameter SerializationPath:
• /users/role,admin,firstName,Alex• /users/role=admin,firstName=Alex
Query:• /users?role=admin&firstName=Alex• /users?role=admin,firstName,Alex
• Parameterized Server support
Our Contributions
https://swagger.io/docs/specification/api-host-and-base-path/
![Page 23: Qt and OpenAPI/Swagger - a tutorial](https://reader030.fdocuments.us/reader030/viewer/2022012718/61b11cd0467e5b57d56c48ae/html5/thumbnails/23.jpg)
A company of the www.basyskom.com | [email protected] Protection notice DIN34 / ISO16016 23
Summary
• Generate boilerplate code generally leads to fewer errors and takes away tedious work
• You don´t have to worry about the communication details
• Integration into a Qt Project works really well
• QML integration could be improved
• Some features of OpenAPI 3.0 are missing
If you are interested in the example project, feel free and visit our blog!
https://blog.basyskom.com/