Introduction

In today’s dynamic application landscapes, seamless communication between different applications is crucial for supporting various business processes. Whether it’s facilitating state transitions, acquiring shared assets, or linking documents to assets, applications often rely on communication with one another. This is where Application Programming Interfaces (APIs) play a pivotal role. Specifically, Web APIs provide a means to interact with applications over the HTTP protocol using web services.

The OpenAPI specification, championed by the OpenAPI Initiative, is one of the multiple specifications to describe a Web API. Widely supported by libraries such as FastAPI for Python and springdoc-openapi for Java/Spring Boot, the OpenAPI specification enables the automatic generation of API specifications for seamless communication. This eradicates the need for manual updates and ensures consistency between the API specification and its implementation, saving developers from potential headaches.

The Power of OpenAPI Specification

The OpenAPI specification is language-agnostic, allowing servers and clients to be written in different languages. This comprehensive specification includes the API’s supported calls, expected HTTP codes, headers, the data objects communicated by the API, etcetera. It serves as a complete reference for the API, making it easier for developers to interpret and use.

With libraries like FastAPI and springdoc-openapi, developers can effortlessly interpret the OpenAPI specification and generate code to communicate with the API. Tools like Swagger UI further facilitate API testing, simplifying server implementation and aiding clients in understanding the API’s functionality.

Introducing sw5_openapi_interface_generator

However, despite the convenience of the OpenAPI specification and these libraries, Smallworld 5 faces a unique challenge. It cannot directly utilize OpenAPI specifications, forcing developers to write all the communication code manually. This is not only a laborious task. It also often leads to overlooked updates when the API specification changes, resulting in rework and slowdown.

To address this issue, I’ve developed the sw5_openapi_interface_generator. This powerful tool takes an API specification and automatically generates Magik code to communicate with the API. By eliminating the need for manual coding, it significantly reduces the development effort and ensures consistency with the API specification. The generator has been thoroughly tested against FastAPI and springdoc-openapi servers and is successfully employed by one of my customers for multiple APIs.

sw5_openapi_interface_generator is shared as an open-source project under the GPLv3 license. The generated code, however, can be freely used without any restrictions. If an alternative license is needed, feel free to contact me directly.

Please note that while the sw5_openapi_interface_generator is designed to be reliable and efficient, it may not fully support all aspects of the OpenAPI specification or may contain minor bugs. Therefore, users are encouraged to utilize it at their own risk. If any issues or improvements are identified, please don’t hesitate to report them through the GitHub issue tracker.

Best Practices for Utilizing the Generated Code

To ensure a smooth development experience, it is recommended to place the generated code in a separate folder, such as generated/. This practice helps distinguish between manually written code and generated code, preventing accidental overwrites. If any modifications to the generated code are necessary, create a separate file, like overrides.magik, to clearly indicate the changes and avoid confusion.

APIs often require multiple calls to complete tasks. To address this, consider creating an engine that sits in front of the generated API code. This engine can encapsulate complex logic, handling multiple API calls within a single method. Additionally, it can validate input before invoking the API, accommodating specific requirements that might not be expressed in the API spec.

Conclusion

The sw5_openapi_interface_generator is a valuable tool that significantly simplifies API communication in Smallworld. By automatically generating Magik code from the OpenAPI specification, it reduces tedious manual work, streamlines development, and ensures consistency. Give it a try and explore the vast potential it offers to enhance your Smallworld development experience.

To access the sw5_openapi_interface_generator and contribute to its development, visit the sw5_openapi_interface_generator GitHub repository. Happy coding!