Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Well, by reading your API’s structure, we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing. Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire API.
Characteristics of a well-designed API :
- Easy to read and work with: A well designed API will be easy to work with, and its resources and associated operations can quickly be memorized by developers who work with it constantly.
- Hard to misuse: Implementing and integrating with an API with good design will be a straightforward process, and writing incorrect code will be a less likely outcome. It has informative feedback, and doesn’t enforce strict guidelines on the API’s end consumer.
- Complete and concise: Finally, a complete API will make it possible for developers to make full- fledged applications against the data you expose. Completeness happens over time usually, and most API designers and developers incrementally build on top of existing APIs. It is an ideal which every engineer or company with an API must strive towards.
Swagger ช่วยให้อธิบายโครงสร้างของ API เพื่อให้เครื่องสามารถอ่านได้ ความสามารถของ APIs ในการอธิบายโครงสร้างอันยอดเยี่ยมใน Swagger การอ่านโครงสร้าง API ทำให้สามารถสร้างเอกสาร API ที่สวยงามและโต้ตอบได้โดยอัตโนมัติ นอกจากนี้ยังสามารถสร้างไลบรารีไคลเอ็นต์สำหรับ API ในหลายภาษาโดยอัตโนมัติ เช่น การทดสอบอัตโนมัติ Swagger ทำสิ่งนี้โดยขอให้ API ส่งข้อมูลกลับมาในรูปแบบ YAML หรือ JSON ของ API ทั้งหมดของคุณ
ลักษณะของ API ที่ออกแบบมาอย่างดี :
- ง่ายต่อการอ่านและทำงาน: API ที่ออกแบบมาอย่างดีจะใช้งานได้ง่าย และทรัพยากรและการดำเนินการที่เกี่ยวข้องสามารถจดจำได้อย่างรวดเร็ว
- ใช้งานในทางที่ผิดได้ยาก: การใช้งานและการผสานรวมกับ API ที่มีการออกแบบที่ดีจะเป็นกระบวนการที่ไม่ซับซ้อน และการเขียนโค้ดที่ไม่ถูกต้องจะมีโอกาสน้อยลง
- สมบูรณ์และรัดกุม: API ที่สมบูรณ์จะทำให้นักพัฒนาสามารถสร้างแอปพลิเคชันที่ครบถ้วนสมบูรณ์กับข้อมูลที่สามารถเปิดเผยได้ ความสมบูรณ์มักเกิดขึ้นตามกาลเวลา และนักออกแบบและนักพัฒนา API ส่วนใหญ่จะสร้างส่วนเพิ่มจาก API ที่มีอยู่