Does anyone have an easy way to document reusable enums in nestjs using swagger? I don't mean showing them as options in a request. I am looking to document the enums themselves, since they are not very understandable on their own:
export enum ScanState {
SCAN_WAITING_FOR_CAPTURE_DATA = 'SCAN_WAITING_FOR_CAPTURE_DATA',
SCAN_VALIDATING_CAPTURE_DATA = 'SCAN_VALIDATING_CAPTURE_DATA',
SCAN_CAPTURE_DATA_VALID = 'SCAN_CAPTURE_DATA_VALID',
SCAN_CAPTURE_DATA_INVALID = 'SCAN_CAPTURE_DATA_INVALID',
}
I would think there would be some kind of #Schema or #ApiAdditionalProperty or something I could just add to the top of the enum for documentation, which would then be added to the Schemas portion of the Swagger docs similar to how it already works with classes. I'm using #nestjs/swagger version 6.0.4.
Seems to be a classic Swagger/NestJS problem, but I haven't been able to find a good solution elsewhere. Thank you, any help is greatly appreciated!
Related
I am working with GraphQL (in Java) and I would like to find a way to do the following:
I need the possibility to constantly adapt the GraphQL schema at runtime without restart. In particular I need to be able to add new fields to GraphQL types. Moreover I need the possibility to be able to write resolvers which can handle this dynamic schema.
I do not have example code yet, so just think of the simplest example (one GraphQL type with several fields that can all be of different type).
My problem is that I am quite new in GraphQL and I do not have a lot of experience with it. Of course I looked for a solution on the internet, but I did not find one yet (or just did not notice that I found it due to my lacking experience with GraphQL).
The only interesting discovery I made is this: exposing dynamic schemas with graphql . But I do not understand how this solution works because 1) I do not know how to reload the schema at runtime and 2) I do not know how to write the resolvers so that they can handle that dynamic schema.
So can anybody help me with my problem and/or can answer my questions regarding the link I found?
I am very thankful for every help, no matter how extensive it is. Like I told before, I am quite new in GraphQL. Therefore I would be also very thankful for links to examples (if possible), so that I can understand better.
Thank you very much in advance.
#userongithub0 you may take a look at GraphQL Schema Directives
And specifically on the rest directive
First of all, don't ever try to do that or use only if there're some very strict situations. Here's why:
A schema is like a contract between the front-end & backend & on change, it can lead to instability between both of them very quickly.
If you try to change the schema of GraphQL, it might fail to connect properly with your resolvers & consecutively with your database as well.
Whenever there's is a change in the schema the GraphQL server (the server handler, in general) needs to be restarted (recompile) & it will take time, hence results in high response time.
No matter what language you are using, you should always see it as a red flag. In my opinion, it will be a really bad practice.
We're providing a public API that we use internally but also provide to our SaaS users as a feature. I have a Model, a ModelSerializer and a ModelViewSet. Everything is functional but it's blurting out the Model help_text for the description in the API documentation.
While this works for some fields, we would like to be a lot more explicit for API users, providing examples, not just explanations of guidance.
I realise I can redefine each field in a Serializer (with the same name, then just add a new help_text argument, but this is pretty boring work.
Can I provide (eg) a dictionary of field names and their text?
If not, how can I intercede in the documentation process to make something like that work?
Also, related, is there a way to provide a full example for each Viewset endpoint? Eg showing what is submitted and returned, like a lot of popular APIs do (Stripe as an example). Or am I asking too much from DRF's documentation generation? Should I handle this all externally?
To override help_text values coming from the models, you'll need to use your own schema generator subclass and override get_path_fields. There you'd be able to prioritize a mapping on the viewset (as you envision) over the model fields help_text values.
On adjusting the example generation - you could define a JSON language which just deals with raw JSON and illustrate the request side of things pretty easily, however, illustrating responses is difficult without really getting deep into the plumbing, as the default schema generated does not contain response structure data.
I'm currently using Apache UIMA to retrieve a list of occurrences of phenotype terms. However, the documentation (Why do so many bioinformatics software APIs lack good documentation!) seems to only point towards the CAS debugger GUI rather than being able to return the annotation index.
http://i.stack.imgur.com/giNoj.png - Picture of the CAS GUI, I want it to return the annotation index in the bottom left
Like I said, the docs don't really answer this (https://uima.apache.org/documentation.html), but generally I want to be able to call the process() method in the Annotator class, and for it to return the annotation index once it has found any and all occurrences.
Sorry if it's a silly question with an obvious answer, I've spent three hours going through the docs so far and haven't come any closer to finding the answer, if anyone's tried integrating it into a project in a similar way and can point me in the right direction, it would be much appreciated!
The process methods change the state inside the CAS. After calling ae.process(cas) or ae.process(jcas), the annotations are stored in the CAS. Just get the annotation index from the (J)Cas.
Apache uimaFIT might also be convenient for you as it provides various "select" methods to access annotations in the (J)CAS, e.g.:
// CAS version
Type tokenType = CasUtil.getType(cas, "my.Token");
for (AnnotationFS token : CasUtil.select(cas, tokenType)) {
...
}
// JCas version
for (Token token : JCasUtil.select(jcas, Token.class)) {
...
}
More detailed information on this API can be found in the uimaFIT documentation, in particular in the sections on pipelines and on access methods.
Disclosure: I am working on Apache uimaFIT.
maybe it's a silly thing... I'm trying to use
- (id)getArgumentAtIndexAsObject:(NSInteger)argIndex;
From NSInvocation+OCMAdditions.h, but I can't import the Category and if try to use the method is not available.
I'm using cocoaPods to get OCMock and I imported the header class:
#import <OCMock/OCMock.h>
maybe is a setting in cocoaPods?
Any help is appreciated.
Thanks
Finally as Erick said is not possible to use that method, so I used this way:
//We mock the methods loginWithUser
[[[controllerMocked stub] andDo:^(NSInvocation *invocation) {
void (^sucessBlock)(NSString *token);
[invocation getArgument:&sucessBlock atIndex:4];
sucessBlock(#"1234567890");
}] loginWithUser:[OCMArg any] andPassword:[OCMArg any] withSuccess:[OCMArg any] withFailure:[OCMArg any]];
However the right answer is the Erick one :)
This is a private method intended to be used by OCMock internally. It is not exported as part of the pod.
The reason is that I'm trying to keep the public API of OCMock, which must be supported for a long time, as small as possible.
If you want to use getArgumentAtIndexAsObject: in your project do so by adding the corresponding header file to your project. However, there is no guarantee that the method will be available in future versions of OCMock.
My python code has fields named like field_name which is fine for python and works well with Django.
Lots of Javascript linters want you to make it fieldName or they whine at you a lot.
Trying to find a nice common ground between the two, I've written serializers like
class MySerializer(serializers.ModelSerializer):
fieldName = serializers.WritableField(source='field_name', required=True)
class Meta:
model = Widget
exclude = ('field_name',)
Problem is that this does NOT replace the external representation of field_name with fieldName, it sends both fieldName and field_name. So I told it to exclude the ('field_name'). Then when you are trying to save, it gets really upset because field_name isn't present, or fieldName isn't a member of the object.
I had thought that mapping would be a good way to do this, but it doesn't appear to be so. Is there someway to map the names from python -> javascript so the code can look pretty on both ends?
Found a package that takes care of it at the json level:
https://pypi.org/project/djangorestframework-camel-case/
Documentation is very sparse, but it appears to work, and integrating it is trivial (which might explain the sparse documentation).
You code should be working. So there's something missing from the example
The thing that comes to mind is your fields value — what do you have specified there? It's generally better to explicitly specify the fields you want there rather than using exclude — it takes longer to set up (maybe) but it'll save time in the long run.
If fieldName is included in fields and field_name is not I would expect your code to work.
(Perhaps show a little more if that doesn't solve it.)
Update after edit to question
Ok. Yes. You should specify the fields you want. Your fieldName is acting as an extra field with its source as field_name — this sort of thing is useful when using SerializerMethodField for example.
Update: Extra Solution
There's a ticket asking about Camel-casing field names for better compatibility with e.g. JavaScript clients. This links to a Gist with a working solution via custom renderer and parser classes.