Initial Project Outline

Introduction

The engineering Outreach office has been working on developing a solution to manage the new services and products that they offer. In the winter of 2018, the initiative for a new system started with implementing the architecture of the system. As of now, the system has grown to be a large scale system that uses multiple technologies to manage their code base. Which brings us to this project, the engineering outreach office is looking to automatically build documentation on their RESTful services using Swagger files.

Swagger Files

Swagger files use data format known as YAML to describe the functionality of a RESTful service which could be used by other applications, such as Postman SoapUI and others. The engineering outreach office wants to automate the creation of these Swagger files based off of annotations used within their codebase.

Essentially when a project builds itself it would then create these Swagger files which could then be used to help describe the following information to front-end system developers:

• Expected query string parameters
• Expected header values
• Expected HTTP code responses
• Expected output
• Data format
• Data type values (Strings, Integers, Floats, Dates, Time, etc…)
• RESTful URL name

Conclusion

With this in mind, we believe that the solution will help developers better document their code, and bridge the gap between front-end system development and back-end system development. We would then open source this solution and allow others to contribute and use this solution. Allowing others to write self-documenting RESTful services.