Comments (3)
Actually I would go for a more types.
If the value is presented as String you could always fake parse/raw copy it to the target type:
ValueType.DETECT
= Default setting, attempt to guess the value type based on the annotated field
ValueType.STRING
= Just use the string as string. (For Strings and enums)
ValueType.INTEGER
= For Integers/Longs and BigInteger(?)
ValueType.FLOAT/DECIMAL
= For Float/Double and BigDecimal(?)
ValueType.RAW
= For some complex data without proper data schema. (ex Map<String,Object>
)
(EDIT: Actually INTEGER
, FLOAT/DECIMAL
and RAW
could be combined to just one because they behave the same)
@interface ApiExample {
String value();
ValueType type() default ValueType.DETECT;
}
There is no need to actualy parse the example value as it can be just printed using @JsonRawValue
(maybe ValueType.STRING
needs automatically added extra quotes).
from livedoc.
Funny that you mention inserting a JSON value, because I thought about it right after posting this issue.
That being said, I'm not sure how much value this brings to the users, especially for complex objects with many fields. I really wanted them to be able to write new MyThing(param1, param2)
as default value, and their customized Jackson mapper would have done the serialization job, but annotations don't permit that, which is a pity.
The JSON value approach has a few drawbacks:
- it forces users to write JSON, which is inconvenient, especially for big objects
- it forces users to maintain the example JSONs each time they customize their Jackson configuration (dates, enums, arrays...)
- if we don't want to force the users to write formatted JSON, we would need to deserialize the JSON into an object of the right class (to respect Jackson config properly), and then serialize it back to JSON. This is a problem to me because users don't necessary want to write deserializable classes if serialization is enough. This behaviour could be changed via a Livedoc setting, though.
Because of this, I'm not sure we should add complexity to Livedoc if there is no real value added. That being said, these drawbacks are not that important considering that providing example JSON for objects should be occasional and not a practice users should apply all over the code base. That's why I may consider it anyway when creating the annotation(s).
Regarding @JsonRawValue
, where do you think we could use it? Livedoc template objects are all maps or primitives, so there is no place to put this annotation, unless we deserialize to a declared class. However, in that case, it would be in the user's classes, and this would affect production behaviour, not only the doc. Did you have an idea in particular? Or were you merely pointing at the feature, just in case?
from livedoc.
I also thought about maybe allowing Livedoc to instantiate the object using a no-arg constructor if present. This could be specified via an annotation, or maybe be the default behaviour instead of exploring properties.
For instance, Livedoc could try to find a no-arg constructor on the class, and if not found, fallback to the current behaviour of exploring properties and creating a Map<String, Object>
. That way, Livedoc would respect their Jackson config as much as possible.
from livedoc.
Related Issues (20)
- JSON output is affected by the user's custom ObjectMapper HOT 1
- Mime types not read from GetMapping and the likes
- Use build-info version as fallback for livedoc.version property
- Livedoc endpoint shows wrong livedoc version and badly parseable build date HOT 2
- Incorrect Livedoc UI version in the webjar artifact
- Support links to doc elements from descriptions and free text pages HOT 1
- Remove the "flows" feature
- Hide "Flows" tab when no flows are present in the doc HOT 1
- Re-sync doc even if found in local storage
- HTML is not properly displayed in ApiType descriptions HOT 1
- Issues with mixed active content HOT 5
- Export to file and import from file HOT 2
- Livedoc generates duplicate ids HOT 2
- Remove common suffixes HOT 3
- Version the API spec independently from the library HOT 5
- IE11 not working HOT 4
- @RequestMapping using regex not working in UI HOT 4
- Playground URL bar displays 'false' when cleared
- [CVE] Dependency jackson core has CVEs HOT 4
- Publish directly to Maven Central
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from livedoc.