itdoc - Hãy tạo tài liệu API Node.js chính xác mà không cần Swagger

Giới thiệu

Bạn vẫn đang viết tài liệu API thủ công?
Chúng tôi đã tạo ra một mã nguồn mở có thể tự động tạo tài liệu chỉ cần viết test tốt.

Phù hợp cho những ai

• Nhà phát triển backend Node.js / TypeScript
• Từng cảm thấy việc viết tài liệu API phiền phức và lặp đi lặp lại
• Từng gặp tình huống nội dung tài liệu khác với API thực tế khiến việc cộng tác bị rối

Liên kết dự án

• Github : https://github.com/do-pa/itdoc
• Tài liệu chính thức : https://itdoc.kr

[kansm]

Chỉ đọc tài liệu thì mình vẫn chưa hiểu lắm.. Ý là có thể thay thế Swagger đúng không?
Hay là cứ hiểu là nó còn vượt trội hơn Swagger nữa nhỉ?? haha

[penekhun]

Có vẻ README cần được bổ sung kỹ hơn một chút. Cảm ơn bạn đã để lại bình luận!

https://itdoc.kr/blog/itdoc

Tôi tin rằng nếu bạn đọc thử bài viết này, thắc mắc của bạn sẽ được giải đáp nhé haha

[jhc9639]

Khá ổn haha

[penekhun]

Xin cảm ơn 🙇‍♂️

[baeba]

Như bạn biết đấy..
Cũng có cả thứ này nữa.
https://github.com/swagger-api/swagger-codegen

Nếu là định dạng tài liệu openapi thì..
Nó sẽ sinh ra mã node.js.
Dùng thử rồi thì thấy.. cũng khá ổn..

Nó tạo được cả mã phía server lẫn phía client..
Trước hết, nếu đã có kinh nghiệm code liên quan đến Rest API từ trước
thì có lẽ sẽ được hỗ trợ khá nhiều.

Nếu tìm kỹ thì.. còn có những bản fork của đoạn mã đó được cập nhật nhiều hơn nữa.

[penekhun]

Cảm ơn bạn vì bình luận rất hay!
Tôi cũng nghĩ công cụ mà bạn nhắc đến là một công cụ rất tuyệt vời.

Nhân dịp này, nếu giải thích ngắn gọn về sự khác biệt với itdoc,
sự khác biệt cốt lõi chính là cách tiếp cận Design-First so với Code-First (itdoc).

Một số nhóm thích phương thức Design-First, tức là thiết kế đặc tả OpenAPI trước rồi mới bắt đầu phát triển API,
trong khi với các nhóm khác, quy trình Code-First — triển khai mã thực tế trước rồi trích xuất tài liệu sau — có thể tự nhiên hơn.

itdoc là công cụ phù hợp hơn cho trường hợp sau,
điểm đặc trưng là tạo tài liệu dựa trên kiểm thử và trên hành vi thực tế đang chạy. Có lẽ sẽ tốt hơn nếu bạn chọn công cụ phù hợp theo cách phát triển và sở thích của đội ngũ mình!

[k201gun]

Logo thật sự rất dễ thương.

[penekhun]

Cảm ơn bạn 😆

[penekhun]

Bạn có thể tạo tài liệu bằng mã nguồn mà con người có thể đọc được như bên dưới.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "API truy vấn người dùng",  
        tag: "User",  
        description: "Đây là API dùng để truy vấn thông tin chi tiết của một người dùng cụ thể.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("Khi được cung cấp ID người dùng hợp lệ, thông tin chi tiết của người dùng sẽ được trả về.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("ID người dùng hợp lệ", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("ID người dùng", "penek"),  
                    username: field("Tên người dùng", "hun"),  
                    email: field("Email người dùng", "[e-mail]"),  
                    friends: field("Bạn bè của người dùng", ["zagabi", "json"]),  
                })  
        })  
  ....