Original link: https://editor.leonh.space/2022/apiary/
Apiary is a service that allows us to write API specifications, but not only that, API specification files written in accordance with Apiary’s unique Markdown syntax, Apiary will help us generate the interface between files and fake data according to the specification files. This article introduces some of its features. .
Fee plan
Before entering the pit, you must first understand his expenses, so as to avoid being unable to extricate yourself after falling in love.
Apiary currently has free and paid plans, and you can check the difference between each plan on its website, but it must be specially reminded that Apiary has been acquired by Oracle and merged into the Oracle Cloud product line that no one uses in Taiwan. It is doubtful whether it will maintain an independent service in the future. In addition, it is the consistent style of Oracle. If you have any doubts about Oracle, please use it at your own discretion.
Apiary
Back to the topic, Apiary solves the pain points we used to develop APIs:
- The specification file is written first, but the API has not been completed, which makes it impossible to test. You can only skip or pretend that the API is good for testing, which is called blind testing for short.
- The API has been written, but there is no time to write files. As a result, the connection parameters can only be passed by word of mouth like a secret recipe. It is difficult for colleagues at the edge to implement the connection. In the end, because the documentation has been disconnected from the actual implementation, the product is difficult to maintain.
- There are APIs and files, but I don’t know why they can’t be linked together. I’m not sure if the API is wrong or the file is wrong. In short, mistakes are inevitable.
API Blueprint
As mentioned earlier, writing files in Apiary must use its special Markdown syntax. This Markdown variant has its own name API Blueprint .
The syntax of API Blueprint is based on Markdown, but some syntax formats are added for API file requirements.
There are two types of API Blueprint, one is used to define data structure, for example:
# Data Structures ## Blog Post (object) + id: 42 (number, required) + text: Hello World (string) + author (Author) - Author of the blog post. ## Author (object) + name: Boba Fett + email: [email protected]
Should be sensible.
Once you have the data structure, you can use the previously defined data structure in the API definition file, for example:
# Blog Posts [/posts] ## Retrieve All Posts [GET] + Response 200 (application/json) + Attributes (array[Blog Post])
API Blueprint’s syntax is simpler than either XML or JSON on the other hand.
Spec files and fake interfaces
After writing the definition file with API Blueprint, Apiary will generate API files and fake interfaces according to the definitions in the file. For specific examples, please refer to this official example Sample API Documentation . All API interfaces can be used.
Other notable features
In addition to files and interfaces, it is also worth mentioning that Apiary supports GitHub Sync. We can also put API definition files in the program project folder to enjoy the benefits of version control. At the same time, through the mechanism of GitHub Sync, each submission will trigger Apiary also updated the published spec files, which is great.
References
This article is reprinted from: https://editor.leonh.space/2022/apiary/
This site is for inclusion only, and the copyright belongs to the original author.