I needed my Node REST API's to be versioned. I am using swagger 2.0 for the validation middleware and documentation. Currently i have only a single swagger yml file that is used for all purposed.
I am using url prefixes (version number: /v1/... /v2/... etc) to support versioning in my Node Rest API. And i need to support multiple versions at any point of time.
Should i create a separate swagger yml file for each API version? If yes, how to load/manage multiple swagger yml files in the swagger-validation middleware
Does Swagger 2.0 format specification allow definition of versioned paths within the same file.
Swagger does not specify a versioning scheme simply because there is no single solution, and forcing one approach to use the spec would not make sense. Here are common techniques that I've seen:
1) Tie your authentication to a version. I think this is the coolest way to handle versioning but is also the most expensive to support and maintain. Based on, for example the api key being used to access your service, you can keep track of the version that they're expecting to access, and route it to the right server. In this case, you can simply have multiple services running, with different swagger definitions.
2) Use a path part to indicate the version. That means you have a /v2 or /v3 in your path, and based on that, some routing logic points you to the right server. Again, a separate swagger definition.
3) Based on some header, let the user choose what server to talk to. This is pretty unintuitive, but it can work. You should always have a default version (typically the latest)
That said, all of the above solutions mean multiple swagger files. You can use the $ref syntax to link and reuse portions of the spec.
I believe with swagger-tools, you can have multiple instances listening for requests. You just need a routing tier in front of them to handle the different versioning that you choose.
Related
I need to develop an API using NodeJS.But I am not an expert in the nodejs. For the versioning of the API, I found one method where we should keep 2 folders for V1 and V2 versions. Is this the best practise to follow for my API development. Please suggest the best approach? and also suggest the project structure.
Thanks in advance
You should keep the API version as a variable that is configurable (ex. in .env file). You can then version your API by adding the version to the path of your root endpoint (ex. /my-api/v1/api-resource). And when a new version of the API is developed just change the version to v2.
I think that solution of two different directories is not good, because you would have to copy code around and it can quickly mess things up. If you want to have different versions of the API separated you should use some type of version control and develop your v1 on a separate branch (ex. v1) and when the development of that version is complete just create a new branch for the new version (ex. v2).
You should also look into REST as the architectural style of your API: https://restfulapi.net/
I have also created a template for the development of backend systems in Node.js that is based on REST architecture, so you can check out the directory structure and architecture of Node.js projects.
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.
We want to create general public web services and we create customized APIs.
But how to isolate, version and bind those endpoints as a hyperscaled system?
We want to have:
https://api.domain.tld/v1/..
https://api.domain.tld/v2/..
https://api.domain.tld/latest/..
https://api.domain.tld/bosch/v1/..
or
https://domain.tld/api/v1/..
https://domain.tld/api/v2/..
All endpoints should be isolated. Behind an endpoint like https://domain.tld/api/v2/.. exists at least 3 instances of an ASP.NET WebAPI. We do not want to separate versioning by namespaces inside the WebAPI project and use internal route configurations to resolve this.
We want to have this behavior onpremise and aswell on Azure.
Is there any recommendation or best practise and configuration samples out there?
I could only found one thread here (How to version and configure WebApi with multiple aliases) which is very old and there is no answer.
I always use the version as the api route, like you so:
https://domain.tld/api/v1/..
https://domain.tld/api/v2/..
which has always worked fine, but other use url parameters, which I find to be less explicit:
Visual Studio Team Services - API
I would just not recomend you to go with this pattern:
https://api.domain.tld/latest/..
https://api.domain.tld/bosch/v1/..
It would you make you API look a bit messy, but it could make sense if you use logical services in your API:
https://api.domain.tld/service1/v1
https://api.domain.tld/service1/v2
https://api.domain.tld/service2/v1
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.