Generated nodejs server stub is missing routing - swagger

I wanted to try out the code first approach with an OpenAPI spec. For testign purposes I treied the Pet Store Example from SwaggerHub.
In the generated Code I noticed, that there is no logic involving routing.
I also noticed that the code in the service folder is not even used when I run the nodejs server (changing values of example data changes nothing in the output. The API seems to run a swaggerhub server.
Do I have a missunderstanding here, what the swagger code gen does?
On the other hand the client code generation looks how I woudl expect it. Instead of creating rest requests in my client I only have to execute methods of the services.


Based off your question, I would argue you're actually doing a "design-first" approach.
Code-first is when you have an existing codebase/service and you then create your documentation after (whether it is generated or hand written).
A design-first approach is when you create your documentation first, and THEN build out your code. If you have an OpenAPI document, and you're using Swagger codegen to create some code, then you're doing design-first.
As for your question involving routing, all Swagger codegen will do for you is generate some boilerplate code based off of your OpenAPI document. It will not add any business logic, or even route the API calls for you. It is then on you to implement all this logic after the fact.

Related

Using Swagger UI Express / #nestjs/swagger, What is best practice to edit API response codes, descriptions and other properties

So I currently already have the swagger UI set up with the page and everything, but I want to edit the .json file (so I can provide descriptions, error codes and stuff but all in one document). Was just wondering where I should be locating my swagger.json or swagger.yaml file to be able to adjust the API??
If not, what's the best practice for documenting parameters, response codes and descriptions WITHOUT having to do it tediously one by one like below...
Any advice on using swagger with nestjs applications would be much appreciated :) Still very new with using it

.NET Swagger (Swashbuckle): How to handle requests with a very large amount of parameters

We are using OpenAPI to document our APIs. A few of our calls have a very complex structure with nested classes of nested classes with possibly circular references. This is acceptable and required for the actual API. However, the documentation for these endpoints is almost unusable.
We are using swashbuckles .NET-integration to dynamically generate the documentation at startup and scraping the afterwards if there's a need for static documentation.
I have read about using $ref according to swagger specs but I'm not sure this is the use case for it.

Where to add server logic using Swagger codegen with Lumen Server Stub

I have been looking around but haven't been able to find anything concrete on this so apologies if it has been asked before.
I am using Swagger codegen to create a ServerStub for my Lumen API project that I am making which is working just fine. My confusion comes from where am I meant to put in my server side logic for connecting to the database, etc.
All files in the middleware and controllers folders, as well as routers.php explicitly state Do not edit the class manually in the header comments of each class. So I'm a bit confused where I am supposed to put my logic after the creation of the Server Stub.
Can anybody shed light on where to I put my implementation of the project to use the Server Stub provided? Because the comments tells me not to edit the class, I feel like my implementation is meant to be abstracted away somewhere but I'm just not sure where.
Appreciate any help on the issue. Thanks.

Swagger best practices

I am currently defining a Rest API and I intend to use Swagger to document it.
I've already started to define my API specifications with the Open Api Specification in YAML into the Swagger-Editor.
Then, I understand that I will provide that file to the Swagger-codegen to generate a server implementation, and also to the Swagger-UI (whose statics files will be previously paste to my server) to expose the interactive documentation .
According to Swagger, this is the top-down approach.
But later, I will probably need to modify this API, and I want to do it via by this tediously YAML file previously defined, to keep the API easily modifiable by anyone (and Language-agnostic).
Does the way to do this is to modify the definition file and then re-use Swagger-codegen ? By this approach, I guess so that I can't even lightly modify the API directly in the implementation server code without risking to have a out of date documentation.
And If I chose to do the bottom-up approach (via Swagger-core annotation), I will restrain all my further modifications to occur in the implementation server code, and my initial definition file will never be usable again.
So another question would be : Is there a common way to deal with Swagger when we want to modify the API both via the specification file and via the implementation server code (I suppose that the file that Swagger-core can generate me from my code, will never looks like my initial one that I defined by hand).

To maintain the API documentation, the best course of action that i can suggest is to follow a hybrid approach.
Initially, when you have to do bulk development, go for the top down approach. This will reduce the initial set up and coding effort. That's the basic idea behind any codegen.
Then, when it comes to maintaining the APIs, or adding a few new ones every day (or week), follow the bottom up approach. You will already have the previous code, the only thing you'll need to do is add some more annotations or API definitions.
Going for top-down iteratively defeats the purpose of code maintenance. Boiler plates and self generated code are there to give you a quick start, not for sustenance.

My opinion may be biased.
For API client, there should not be a need to customize it in most cases. If you find that you need to customize it to meet your requirement, it may worth starting a discussion via https://github.com/swagger-api/swagger-codegen/issues/new (and also please check what are the options available to customize the output, e.g. for PHP, run java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php)
For server stub, ideally the developers only need to focus on the business/application logic and regenerate the server stub when adding/deleting/updating endpoints (but I don't think all the server stubs can achieve that yet)
Disclaimer: I'm the top contributor to Swagger Codegen

Breeze save bundle format

I am using Breeze JS and would like to implement a server with full CRUD functionality using Progress Openedge. The Breeze website talks a lot about being able to write your own server implementation but I can find no information describing the format of a save bundle that Breeze sends to the server. Does anyone know of any documentation or schema?

The documentation for this is buried in the DataServiceAdapters page. Look about halfway down, under the heading saveChanges (saveContext, saveBundle) -> promise.
There's an example of what the JSON looks like in this SO answer.

The SaveBundle is not documented for a very good reason: it has no definition in BreezeJS!
It could be any serialized object that your server requires to satisfy yoursaveChanges work flow. You can see that this is true by examining the a60_abstractDataServiceAdapter.js source in github:
proto._prepareSaveBundle = function (/*saveContext, saveBundle*/) {
...
throw new Error("Need a concrete implementation of _prepareSaveBundle");
};
Breeze does ship with an implementation b00_breeze.dataService.webApi that satisfies the expectations of the companion Breeze ASP.NET Web API helper classes such as ContextProvider. This implementation is worth studying if you decide to write your own server support code.
But it is only one of many possible implementations. An OData web server, for example, requires an entirely different package and format for "$batch" change-set saves. Only you know what's right for your "Progress Openedge" server.
All that said, we do delve into some critical aspects of the SaveBundle destined for Breeze Web API services in the documentation for "ContextProvider".
Feel free to follow-up with more specific questions after you've read that.

Resources