I'm trying to document my API using Swagger, but if I do the documentation by myself and manually, I'll spent a lot of time, and then I saw this question on SO, and the last answer is about the express-oas-generator that seem's to be a good tool.
Generated my documentation with success, but the POST didn't made my Payload documentation, and without this, some developer could thought that my POST don't need a payload to send
All that I did was following the documentation, made some test's using the API and call the methods using POSTMAN. The express-oas-generator, generates the documentation, but without the payload in POST method.
Someone has already pass through this ?
Related
I'm a student who's newbie to the world of APIs and I'm working on an assignment where I have to create a NodeJs rest API that would call a SOAP service, transfer the XML response into a JSON object and return it to my angular project that calls this API.
I have looked around and found very little information about this, so is there a good place for me to start (Tutorial, courses, etc..) ?
looking forward to receiving answers because my passing grade is on the line :( </3
You need to break up this problem into multiple steps.
How do we make a rest-api in nodejs?
See a link like: https://www.codementor.io/#olatundegaruba/nodejs-restful-apis-in-10-minutes-q0sgsfhbd
OR How to best create a RESTful API in Node.js
How do we call a soap service from nodejs?
See e.g. SOAP Request using nodejs
How do we call our rest-api from angular?
https://angular.io/guide/http OR
Call Rest API From Angular Application
So break the problem up into steps, find the tutorials that help you implement that part, and put it all together.
Also use console.log and JSON.Stringify to debug your objects. E.g. see: https://levelup.gitconnected.com/5-ways-to-log-an-object-to-the-console-in-javascript-7b995c56af5a
when trying to post a WakeUp event with a JSON body to the Alexa events API using nodejs with axios or request-promise, the API always returns an error 500.
I posted to an online endpoint to actually see what gets posted and learned that the post body gets truncated which obviously results in invalid json. I abstracted the problem and tried to run it from a virgin nodejs installation by using repl.it and the result is the same.
Interestingly enough, there seems to be a relation between the length of the header and the body. So when I shorten the auth token in the header, more characters of the body get transferred. If I shorten the long tokens in the body to about 450 to 500 characters (it seems to vary) the whole request gets through. Obviously this is not a solution, because the tokens are needed for authentication.
When I experimented with the axios version used lowering it to 0.10 I once got a result but posting again lead to another 500. If I post often enough some requests get trough complete, even on the current axios version. I also tried using request-promise with the same outcome.
I got the feeling that I made a really stupid mistake but I can't find it and I really couldn't find anything on this topic, so it's driving me crazy. Any help would be greatly appreciated!
This looks like a tricky one.. first of all, I don't think you're making a really stupid mistake. It looks to me like one of the low-level modules doesn't like something in the POST body for some reason (really weird.).. I've played about with this and I'm getting exactly the same behaviour with both Axios and Request.. if I comment out the tokens (correlationToken and bearer token ) everything works fine.
If I test this locally, everything works as it should (e.g. set up express server and log POST body).
Also posting to https://postman-echo.com/post works as expected (with the original post data)..
I've created this here: https://repl.it/repls/YoungPuzzlingMonad
It looks to me like the original request to http://posthere.io is failing because of the request size only. If you try a very basic POST with a large JSON body you get the same result.
I get the same result with superagent too.. this leads me to believe this is something server side...
This was not related to the post request at all. The reason for the error after sending the WakeUp event was the missing configuration parameter containing the MACAdresses in the Alexa.WakeOnLANController interface.
I used the AlexaResponse class to add the capability via createPayloadEndpointCapability which had not been modified to support the "new" WakeOnLANController interface yet.
It's a pity that the discovery was accepted and my WOL-capable device was added to my smart home devices although a required parameter was missing :(
posthere.io cutting off long post bodys cost me quite a few hours... On the upside, I go to know many different ways of issuing a post request in node ;)
Thanks again Terry for investigating!
I am practicing Node JS and Angular from past one month. But I am not sure about doing one thing. Whether I should send my errors from my node API using Headers or a JSON Object with the key as an error in my Body...
I have checked some forums, but there is no perfect answer out there. So please spend some time to answer my question guys. Thanks in advance.
Edited: I am using JSON Web Token in my Body part as JSON Format in Login
Well this is quite subjective to answer and will definitely have multiple strategies to work with. This is what I'm doing for my APIs, hope this is useful.
Error messages (JSON) are sent as response body having keys such as "errType" and "errDetail" and maintain this to avoid integration pain. Sometimes, if API is expected to be used by only backend developers, sending some technical error information using key as "errReason".
Send exact response status code like 400, 413 and so on for more clarity.
Not returning any additional header for error reporting.
Let me know your thoughts.
I am very new to Salesforce and it's API.
I am having a sandbox org and with it I have url, username, password, security token and last but not the least partner.wsdl
My aim was to connect and retrieve/create data.
Technologies at hand was nodejs
So here is how I started.
I searched over the internet and came to know that I need to create a client, SOAP client in order to login, create the connection and use that connection to create and access the Leads data.So I followed this sample where the wsdl was being consumed.
So I was able to connect
I was very happy on this success and then suddenly I wasn't able to identify/find a way where I can get the sObject.I looked hard for this but no luck. So posted a question on SO
Meanwhile I also looked for other node module and found jsforce
I used jsforce starting guide and created a client that was connecting to salesforce however without using the wsdl file.
Again I was happy, even more happy because I was having the sObject with me.
Now, what is the fundamental difference if I login using the local wsdl file and without wsdl file in the language of salesforce. Which one is the correct way of logging in?
Sorry if this question is not according to SO rules or if there is a typo.
I'm the author of jsforce you mentioned.
In that lib we use REST API mostly and SOAP APIs are only used in some specific calls like login or metadata. Even in such calls we don't use WSDLs because there's no good lib to generate client modules from WSDL in JavaScript/Node.js area. Instead we wrote modules for each APIs which generate SOAP XML strings and parse the response XML.
It is enough because these API message schema are static and fiesible in the specific version, unlike SOAP API Enterprise WSDL differs in organizations. So we can hard code the client module directly w/o generate it from WSDL.
I'm working on a restAPI using Express.js and I'm wondering if there is a way for me to generate API documents that allow a user to view API definitions or possibly even try out the API call?
What you are looking for is a good JavaScript documentation generator. I found a decent one here http://apidocjs.com/example/.
This will allow you to use just Express as OP asked.
Swagger isn't for generating docs, it's for making APIs. So you are going to need to learn a full system to get that feature.
I found a couple more here that I haven't fully looked into yet which seem promising:
Docco here JSDoc here and an article on Documentor for Node
Swagger is an amazing project for auto generating API documentation. It includes an Express module.
http://swagger.io/
https://github.com/wordnik/swagger-node-express
I found this library to be very useful when it comes to keeping your documentation and route declaration logic close together:
https://www.npmjs.com/package/swagger-jsdoc
If you use Postman while developing you might already have a Postman collection containing the most relevant calls.
If that is the case Postman has a docs feature https://learning.postman.com/docs/publishing-your-api/documenting-your-api/