René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"General overview of current problems with the specs","articleBody":"Hi all,\n\nThe current state of the Open API specs provided - which are linked in the `README` for some reason by the way, but why aren't they files maintained in this repo? - is valid and spec compliant, but it lacks the polish and clarity you'd expect from a production-grade, SDK-generating spec.\n\nThis last part is very significant: Contentstack maintains a set of SDKs in several languages which are manually developed rather than automatically generated, which adds a lot of friction when synchronising all of the SDKs in the target languages and when the underlying API changes (e.g. new functionality is added to existing endpoints, new endpoints are added, etc.). If the Open API specs were cleaner and more idiomatic, the company could just maintain the spec itself and generate all of the client SDKs (for current and possibly more supported languages) with a single automatic code generation tool.\n\nOne example is the `operationId` parameter. While they are unique across endpoints, they are all in lowercase (the format recommends camelCase) and in some cases they are unwieldy. Operation IDs like `getallentries|getallentryvariants|equalsoperator|...` violate the principle that `operationId` should be a unique and concise identifier for codegen and SDK generation.\n\nAnother example: many parameter `description`s are inaccurate or copy-pasted (e.g. `\"Enter the actual query that will be executed...\"` appears for fields that are not JSON queries).\n\nOne more: parameter names like `include[]` and `only[BASE][]` are technically allowed, but not idiomatic. Better practice is to document them with `style: form` and `explode: true`, and clarify in the description. Parameters like `only[BASE][]` would be better modeled using structured query object modeling or clearly defined array fields.\n\nA general problem throughout is the overloading of `description` and `summary` fields: `summary` is crammed with multiple use cases instead of a brief 1-line summary, and `description` includes tons of raw HTML - valid per spec, but not best practice. These fields are intended for humans (e.g. devs using Swagger UI), so readability is key. \n\nInterestingly, some parts of the specs suffer from the inverse of the above: a 200 response with just `description: \"\"` and no schema or example is valid, but under-documented.\n\nUltimately, as it stands, the Open API specs are serviceable but unworkable for any of the more exciting use cases that the format can provide. Anyone interested in leveraging the specs offered is forced to sanitise or post-process them - e.g. trimming HTML, rewriting parameter names, and simplifying operation summaries/IDs.","author":{"url":"https://github.com/glhrmv","@type":"Person","name":"glhrmv"},"datePublished":"2025-06-22T17:58:01.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/10/contentstack-openapi/issues/10"}