In web application development, your team use OpenAPI document in many cases when you separate backend and frontend.

But, the API specification document based on OpenAPI is written in yaml or json format. Then it is a very stressful task.

Also, writing up the API document doesn't mean completing by nature. It is a very tiresome task to keep updating document as a project progress.
(Or rather, it is common not to update at all after it is first created because of maintenance costs. And there is a big difference between actual API behavior and API document.)

There are some services to help you write API specification and visualize it graphically, but there are no standard services
So, many developers struggle to decide what is the best approach for this project.

I had a hard time in my current project too.
After researching a lot of different services and applications, I finally found an effective service.

In fact, I introduced it to my clients and my friends, then I received their good replies.

Let me get straight to the point.
We decided to proceed as below.

• Use the service called "Stoplight" that helps writing OpenAPI document based on GUI. We can import/export yaml files.
• Use "Prism" as a mock server. We can use yaml file as it is and launch using only one command.

Here is the details to decide to use services above.

Development Environment

For frontend, We hired a software vendor that specializes in drawing complicated map.

Our team is in charge of backend.

Main function of backend is done, but API for the vendor has not been touched, neither API design.

In short, backend anf frontend has not been started yet.
The rough requirement is already specified. Our team will decide the details.

We will make new function from scratch, so there are no mock server neither infrastructure ready.

It is required to show a lot of information on the map.
But, we have no idea what data is necessary, what is the suited data format.
It means, we should collaborate with the vendor.

Therefore, we should't give tasks without specification document.

About the adapted services

1．Stoplight

https://stoplight.io/

It helps writing OpenAPI document based on GUI.

You would understand better with images rather than reading explanations.
*It is sample API document of pet store from OpenAPI.

For those familiar with API, you can intuitively understand it.

As you can see, you can edit endpoints, HTTP methods, query parameters, and response parameters based on GUI.

As an additional outstanding feature, you can use it as yaml file.

The generated yaml file can be executed with other OpenAPI plugins.
(This image is when using VSCope plugin "OpenAPI (Swagger) Editor")

It is possible to not only export yaml file but also import yaml file.

It is free to use by yourself, but you can also share with other developers by subscribing paid plan

2．Prism

https://stoplight.io/open-source/prism

In short, "The application that let user use yaml file as a mock server."

You can intuitively understand it with an image too.

As below, by specifying yaml file in command line and executing, the mock server will be launched. ( "-p" is port number)

This is the result of executing with curl command.

As above, you can easily launch mock server without preparing source code and execution environment.

It is incredibly fantastic application, and even more, you can install it very easily with "npm install" command.

The sample command is here.
(Please refer to the official document for details.)

// install
npm install -g @stoplight/prism-cli

// Start mock server from yaml file
prism mock swagger-petstore.yaml -p 4010

I install it globally in my local machine, because it doesn't clutter your environment and doesn't required strict node version.

Explanation of the process

1. Create API speciation in yaml file using Stoplight based on GUI.
2. Share it with the vendor in GitHub repository.

The API document generated by Stoplight is based on OpenAPI standard, so there is no strict requirement to use Stoplight as viewer.
The vendor can use their preferred applications.

About launching mock server, write README file that "Use the application 'Prism'. Here is how to install and execute."

Feedback from the client

I proposed these applications and this approach. The client repose was favorable and told me "It's a good idea! Let's introduce it to other members!".
So, I presented to other development team.

I got positive feedback too, we decided to use it for other projects.

It is not necessary to use Stoplight, but the feature of Prism where "let user use yaml file as a mock server" is truly remarkable.
It is worth considering its adaption.

We haven't started development with the vendor yet, so we will get the result later.
I will update the information.