I want to use Swagger/OpenAPI to standardize documentation efforts. Most of the API's are built with NodeJS and I do integration testing with Mocha & Chai which helps tremendously with quickly making sure the API isn't broken after making changes. From what I understand, using Swagger won't replace my integration test but will make it easy for developers to know how to consume my API. If I can tie my documentation efforts into my test suite, it would make on-going documentation maintenance easier. When i add or modify test, I could update API documents in the same place.
What I was thinking about doing is using YUIDoc or JSDoc which generates API documentation from comments in source. But neither conform to OpenAPI spec. Then I found Swagger-JSdoc and figured I could just put all the comments in my test suite code since I'm already there specifying what to test in the endpoints.
Is there another way/workflow that might be more efficient for new or existing projects? How can I bring my documentation efforts closer to my test suite to improve on-going documentation maintenance?
I just published an npm module for the same. Not sure if you found an alternative, if not please feel free to give it a try.
https://github.com/LmntrX/mocha-swagger/
Install mocha-swagger globally with
npm install -g mocha-swagger
Then execute the following command:
mocha-swagger path/to/project/tests
This command will recursively parse test files in your test directory and generate a basic swagger.json file in current directory.
NB: Please note that the swagger spec generated will only contain your routes, methods and path parameters.
Related
I work into a existing nodeJS project and I would like to use swagger codegen to automate the documentation.
Currently I write the swagger doc after to have code and there is always a time lag between dev and production....
I find two solutions. The first generate the node js projet and after you code inside, but my project have one year and lot of code...
The second solution is to write a syntax in my code and automate the documentation after with command line but this solution don't use yaml and my actual doc is to write is Yaml...
Thanks :)
If your existing node.js project uses Express as its web framework, you could consider using swagger-spec-express which would enable you to simply annotate your existing express api with swagger info.
I have an application developed with Node.js/expressjs. It's working fine. Now I need to generate API document using Swagger. There is a module swagger-node. Do I need to re-write the whole app using this module or is there any other solution to use this module and what is the use of swagger-ui if using swagger-node.
Not from what I can tell. You should be able to generate your swagger project as described, and then just make sure that the information in the yaml file points to the actual controllers and methods that your code uses.
You can create a standalone yaml file that is compliant with Swagger/OpenAPI which can therefore be rendered into Swagger documentation. The Swagger-UI is useful for creating this yaml file. Swagger also offers various tools for testing APIs and generating code -- to use these effectively you will need a method for integrating the controller/model definitions in your yaml file into your existing codebase.
To achieve this integration I typically expose my existing codebase as an api of controller functions -- then import it as a module into the code generated by my documented API. This allows me to trust my API documentation without the burden of porting my whole codebase into Swagger's required directory structure. I believe this is the best currently available approach but is not always worthwhile.
I'm trying to setup a nodejs-express boilerplate for my new project, and this time I want to try doc-driven flow. I've checked couples of packages like swagger-node, swaggerize-express ...etc. They all provide great functionalities.
However, I don't see anything that could support incremental scaffolding when the Swagger file is updated. That means when the spec changes I have to manually check the diff and manually add/modify the new specs. That doesn't sound cool.
Does anyone could share something that is more reasonable? Thanks!!!
Edit:
After trying some frameworks, I decided to use swagger-express-middleware. This framework offers a convenient way to automatically check routes/parameters for your service.
You can use tools like swagger-maven-plugin to incrementally rebuild your server code, which means reading from your api definition and updating/building code as necessary. There are SAAS products like SwaggerHub which enable this as well, by merging code and pushing to git.
I am new to node.js and I have decided that I will be using hapijs for my web and API implementations.
However, I have found that the hapi community built and use lab and code for the test and assertion libraries, which are a rewrite of mocha and chai.
I am having a hard time finding the differences between those libraries.
I know there is the possibility of using them all interchangeably but I would like a more detailed comparison, as I want to define and adhere coding standards and I don't like mix and match of libraries, unless there is a valid reason.
Any feedback is appreciated
When you are planning to build web application using nodejs Hapi is more suitable for it. Writing TTD is important for developer now a days. Lab and code is node framework to help to writing unit test in nodejs. Lab comes with Hapi to cover unit case for endpoint like writing test case for route and covering different scenarios for route. Code is an assertion library. Code is used if you are asserting response code ,response body and any header parameters.
Since the npm module hapi-swagger doesn't support file upload endpoints I need a way to skip certain endpoints in my tests.
I've checked the docs and there's no beforeEach or any way to check which endpoint is which during the test runs.
Currently I've just got my environment set to TEST and have an if in the target handler but that's messy and complicated.
Is there any way to skip endpoints?
I am not quite sure of what you are trying to achieve above. The use of tags can create groups of endpoints. Its often used for pre-release or beta groupings. This maybe of use to you.
The latest version of hapi-swagger now also supports basic file uplaods, so you maybe able skip this issue.
Both tags and file uploads are cover in the project readme and code examples of there use can be found in the https://github.com/glennjones/be-more-hapi project.