blablabla1234678 / REST

REST API and client with HATEOAS
0 stars 0 forks source link

Add documentation generation #12

Open blablabla1234678 opened 1 month ago

blablabla1234678 commented 1 month ago

We need to support documentation generation. It is not hard based on the JSON file. Each hyperlink and data type can get a section. The format can be MD, HTML, SPA? I think the best way would be SPA which loads the JSON file and displays it as as documentation. What else do we need?

blablabla1234678 commented 1 month ago

We need versioning. We need detailed description of each hyperlink and data type.

blablabla1234678 commented 1 month ago
    const docs = {
        main: {
            type: "Hyperlink",
            method: "get",
            uri: "/",
            response: {
                type: "Object"
            }
        },
        registerPerson: {
            type: "Hyperlink",
            method: "post",
            uri: "/people",
            request: {
                type: "FlatObject",
                items: {
                    name: {
                        type: "Name",
                        required: true
                    },
                    age: {
                        type: "Age",
                        required: true
                    },
                    gender: {
                        type: "Gender"
                    }
                }
            },
            response: {
                type: "Person"
            }
        },
        listPeople: {
            type: "Hyperlink",
            method: "get",
            uri: "/people?{page}",
            request: {
                type: "FlatObject",
                items: {
                    page: {
                        type: "Number"
                    }
                }
            },
            response: {
                type: "People"
            }
        },
        People: {
            type: "Array",
            items: {type: "Person"}
        },
        Person: {
            type: "Object",
            items: {
                id: {type: "Number"},
                name: {type: "Name"},
                age: {type: "Age"},
                gender: {type: "Gender"}
            }
        },
        Name: {
            type: "String",
            length: {
                min: 3,
                max: 255
            }
        },
        Age: {
            type: "Number",
            range: {
                min: 18,
                max: 150
            }
        },
        Gender: {
            type: "Number",
            alternatives: [1,2,3]
        }
    };
blablabla1234678 commented 1 month ago

docs.version docs.description docs.main.description docs.Person.description

blablabla1234678 commented 1 month ago

For documentation generation we can use the DocumentationIterator or at least the DocumentationParser.