สรุปบทความ Using OpenAPI to Build Smart APIs for Dumb Machines

ถ้าพูดถึง APIs ทุกบริษัทต้อง APIs แม้กะทั้งบริษัทที่ไม่ได้ทำเกี่ยวกับ tech ก็ตาม ซึ่งการที่มี OpenAPI เราต้องมีเอกสารในคนเหลา Developer อ่าน เราก็รู้กันดีนะครับว่าเหล่า Developer ทั้งหลายนั้นไม่ค่อนจะถูกกันงานเอกสารสักเท่าไร จึงทำให้บังเกิดความคิดที่ว่าเรามีโปรแกรมสำหรับสร้างเอกสาร API Spec ตามที่ code ถูกเขียนดีว่าไหม

Swagger จึงเกิดขึ้นมาในตอนแรกก่อนที่จะถูก rebrand ใหม่ในชื่อ OpenAPI ซึ่งอยู่ภายใต้ OpenAPI initiative

ตัวของ Swagger สามารถสร้าง API Spec ได้ทั้ง generate ผ่าน UI/สร้างผ่าน json/yml file

"paths": {
    "/athletes/{id}/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get Athlete Stats",
        "description": "Returns the activity stats of an athlete.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The identifier of the athlete. Must match the authenticated athlete.",
            "required": true,
            "type": "integer"
          },
          {
            "$ref": "#/parameters/page"
          },
          {
            "$ref": "#/parameters/perPage"
          }
        ],
        "tags": [
          "Athletes"
        ],

อีกอย่างตัว Swagger ยังสามารถใส่ syntax บางอย่างเพื่อให้ tools generate API Spec หรือเราสามารถให้ generate อัตโนมัติตาม code ของเรา จะทำให้เอกสาร Spec เป็น version ปัจจุบัน และตัว Open API ยังนำไปสร้าง mock server เพื่อจำลองตัวเองเป็น server ใช้สำหรับหรือจำลองการติดต่อ front-end กับ backend

ตัวอย่างเช่น Java ที่มี annotation

@GET     
  @Path("/{username}")     
  @Operation(summary = "Get user by user name",
    responses = {                     
      @ApiResponse(description = "The user",                                      
         content = @Content(mediaType = "application/json",                                     
         schema = @Schema(implementation = User.class))),                      
      @ApiResponse(responseCode = "400", description = "User not found")})     
  public Response getUserByName(           
     @Parameter(description = "The name that needs to be fetched. Use user1 for testing. ", required = true) @PathParam("username") String username)             
     throws ApiException {
         User user = userData.findUserByName(username);
         if (null != user) {
             return Response.ok().entity(user).build();
         } else {
             throw new NotFoundException(404, "User not found");
         }
     }

ถ้าคุณกำลังจะสร้าง API ใหม่ควรเริ่มจาก API description spec ให้ทุกคนในทีมและลูกค้าได้เห็นจะช่วยให้คนที่เกี่ยวข้องเข้าใจตรงกันแล้วจึงนำ spec ไป implement และยังสามารถกลับมาเช็คได้ว่าทีมได้ทำตาม spec หรือไม่