magidoc
magidoc copied to clipboard
magidoc-org
Query generator for unknown values
Describe what is missing
I'm not sure if this is a missing feature or just not documented, but I have been trying to generate a value for "unknown" scalars and types that are not listed in queryGenerationFactories
This page here mentions that we can use glob syntax, and only the most specific factory will be used. https://magidoc.js.org/plugins/graphql-query-generator
Seems like using '*': 'UNKNOWN' makes it super specific, and it's used even for default scalars and input types.
Is there any official way to do this in the library?
The goal?
If something is not listed in queryGenerationFactories, we want to not throw errors, but just generate the documentation gracefully with some default value for the unknown type. For example UNKNOWN.
The current behaviour is that the generation fails completely and throws errors.
Hi @amanb014.
What you describe here is the expected behaviour at the moment. Magidoc aims to create meaningful documentation for people to understand your API. If we decided to put UNKNOWN in the documentation, it wouldn't help the user understand what they have to input there. In the end, every scalar will resolve in either a string (sometimes with a specific format), a boolean or a number. Magidoc is not able to know by itself what is expected there.
For the other part of your question, the generation factories can in fact be used to represent any type in your API, not just scalars. So when you put a star like that, it will override every type of your API, not just scalars.
The ideal is that you provide a factory for each of your scalars. Generally, APIs have at most a few dozens of these, but it's possible you have more. Just by curiosity, how many scalars to you have approximately, and is there no way you could provide an example for each of these in the config ?
Yep that totally makes sense, and I generally agree with it. I wasn't so concerned about the scalars we have today, but if a new one is added I was generally accepting that we will keep generating docs until the person that added the new scalar adds a more specific example for the data that it generates.
I currently have a setup that's a bit different, and multiple schemas use a single configuration file, and there is a possibility that something gets added and unexpectedly fails the generation.
Hey! Sorry for the late reply. Yes, I understand your concern. So this library has two objectives in the end. We aim to provide the most meaningful documentation possible to help people understand the API, while also staying as little maintenance as possible.
I think whether this feature is necessary depends on what you think. Would you sacrifice a little of the documentation's usefulness for a slightly smaller development effort?
From my point of view, it's part of the developer's role to document it's work. Magidoc already do most of the heavy lifting, all you have left to do is add some scalars in the documentation when you add new ones. If we go with your proposition, they might just as well be forgotten and never documented.
If you still find it meaningful, I have no trouble implementing that, but I definitely would make it the default. It would be added as an option to silently ignore missing types.
I agree with the concept that the developers should be documenting how to generate the documentation properly, whenever new changes come through. If we ignore this, it'll just end up in bugs that we have to resolve later because customers/other developers will complain about UNKNOWNs in the docs.
A better way might be to alert on docs generation being broken so we can fix it. I think it's safe to close this!