Type-safe development through API specifications, and up to Mock Server

When working on front-end development, I often experience cases where the work becomes pending. It is ideal to proceed with the front-end work after planning and back-end development are completed sequentially. Still, in reality, in many cases, the result is performed in parallel with the kick-off for developing a specific function.

If there is no API development, waiting, or minor project changes, the front-end development area modifications that deal with the final product will snowball. I am actively utilizing development and mocking based on specification documents to minimize the number of blockers in this work stage.

Fixing the API spec

Once the requirements and initiatives have been formulated, the stage to fix the API specification is entered before proceeding with feature development. Setting and sharing API specs is a crucial step. If the API specification is unilaterally delivered or omitted, it may cause problems such as not having expected properties in a specific interface or mismatching types. Even if the API specification was unilaterally provided, it was indeed shared.

To prevent this, the steps of fixing and sharing the API specification are for all developers involved in developing the feature. Finally, the agreed API specification goes through the documentation phase, and Stoplight is used.

It is an editor that provides various functions such as API, endpoint, and model design. Additionally, the specification can be updated by linking with the Github repository. Finally, it returns the API specification document in YAML file format.

Automatically creating classes and interfaces containing API functions. The process in this section can be viewed as an example in the GitHub repository. It is time to proceed with development through the fixed API specification. It was said that the Stoplight editor finally returned the YAML file. If you provide this YAML file to Opanapi-generator, it automatically creates classes containing API functions and various interfaces necessary for defining API functions. Install the package, select a generator suitable for the project environment, and run the script to create the API.

~$ yarn add @openapitools/openapi-generator-cli -g
~$ openapi-generator-cli generate -i {yaml or json file} -g {generator name} -o {file path to be created} --config {config file}

The class containing the interface function and the related object interface are automatically created. In fact, I said bluntly, the advantages of automatically creating an API and interface are enormous.

When defining API functions in TypeScript, the amount of typing increases considerably, and the interface of the response object must also be accurately represented. The resources used here also help you focus on your business tasks. In addition, it helps to enable type-safe development based on API specifications by minimizing the potential for dormant errors in the work process.

Take advantage of parallel development productivity through Mocking.

I mentioned above the problem of realistically parallel development in developing a specific function. To minimize the pending state of the front-end development stage, before the actual API is developed, the mocking server is operated to receive the mock data and render it as if it is transmitted. When defining the interface in documenting the API specification, you can enter example data for the interface.

After that, you need to run the mock server. In this case, Prism provided by Stoplight is used. Provide the API specification in the form of Prism, YAML. You can run a mock server based on the API specification locally and receive the example data you wrote when defining the interface.

~$ prism mock {yaml or json file}`

You can focus on front-end development in parallel through the mock server even if the actual API development is not completed. It provides the advantage of maximizing productivity by minimizing the pending state.

As you finish

We talked about solving problems that may occur in a parallel development cycle by applying API specification-based development through Openapi-generator. In a real work environment that is not a development cycle that draws an ideal routine, but in parallel, it would be good to take care of type-safe development based on API specifications and productivity at the same time :)