Introduction
First, let me briefly introduce myself.
I am the CTO of a company called Funseek.
The company's main business is commissioned development, focusing on websites and smartphone applications (iOS and Android).
Recently, the development of websites as well as smartphones have been developed with SPA, and the server side is often processed by receiving responses on the front side with only APIs.
The main part of my work will be architecture selection, design, and source code review.
In this section, we will write about how to create a design document required for API design.
How do you create the API specifications?
I think Swagger, APIBlueprint, etc. are famous for creating API specifications.
I also used to use Swagger and APIBlueprint to create API specifications.
Other than that, I think there is a pattern to create in a free format using your favorite apps such as Word, Excel, etc... (I used to create them in the early days using Google documents, etc.)
Problems
Swagger and APIBlueprint (or any other tool) have to follow their own description rules.
Of course, if you remember the rules, you can easily output the API specification to HTML, PDF, etc., which is very convenient.
At first I was very happy with this.
But after a while, when I tried to write an API specification for another project, I opened a text editor and tried to write it. I've forgotten how to describe it. It always starts in the form of reading the documentation and processing the EXAMPLE. Yes, I always stumble on the starting dash.
So, why not just write it in free format?
In the beginning, I used to write using Google documents. The bad part of this is not limited to API specifications, but I am concerned about the formatting. Fonts here should be a little bigger, rules should be drawn, colors here, etc... The biggest problem with this one is that it takes up a lot of time for non-substantive work.
What you really want to do
Most API specifications have a specific format.
- API name and outline
- Endpoint
- Contents of the Request
- Response Content All you have to do is determine and fill in the following
You don't have to learn how to write your own, just fill in the fields and save. If you share the link, other members can see it with one click (in a nicely presented state, of course).
What I want to do is something as simple as this.
That's why I made it.
https://apibooks.funseek.co.jp/.
It's called APIBooks.
The concept is.
- No unique description rule
- Easy UI operation
- Easy to share with links
is.
You can focus only on the essential tasks and, as a result, save time!
What can you do?
The API specification is completed only by filling in the summary, Request, and Response items in the input field.
The duplicate function eliminates the need to create a similar function from scratch.
Input aids are provided for fixed items such as headers.
You can create as many API specifications as you like.
Can be shared by multiple members.
Importing the existing yml (OpenAPI 2,3)
Easy sharing by issuing API specification URL
Download the API specification as HTML.
At the end.
APIBooks is still a beta version with minimal features implemented.
All the features are now available for free! We'd like to continue to improve the service, so we're looking forward to your feedback!
Top comments (0)