Im writing a new set of APIs mostly in golang and traditionally we have been writing the API and generating the swagger specs for it. However, I bumped into swagger codegen recently. I think it is a good way to manage APIs. This also ensures that our Swagger is always updated.
Do you think there are any disadvantages to using codegen to generate APIs? Can someone point me to articles for pros and cons?
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 2 years ago.
Improve this question
I am new in Swagger and as far as I see it is used to generate API documents autotomatically. In addition to that, I think it is also used to generate frontend by using Swagger Codegen. AT this step, I am confused regarding to using swagger in my project properly.
I have created my backend using .NET Core and API methods are ready. Now, I need to integrate swagger to my project. I have an initial Angular frontend app, but as the code is mixed, I want to create frontend from stratch and then integrate Swagger to it. So;
1. Should I generate frontend using necessary Swagger tools? It does not seems to be good, but if it is used generally and will not be a problem as the project gets bigger, of course I can use that option.
2. If I create the Angular project from stratch, how can I integrate the swagger? Should I generate code by using the ts files of the related components?
3. If I add a new component to the frontend and corresponding API methods to the API where Swagger is already used. Which modification ahould I made? I gave a try and it geneartes a new swagger config file after building the project.
Going off on the comments I made below the question.
Just to clarify what swagger and openApi is, swagger is both a rest api specification (e.g. swaggerSpec.Json) and a set of tools to deal with the specification. For example, swagger codegen, swagger UI etc. Now at some point in time, the specification was renamed from swagger to OpenApi.
This means the specification is called OpenApi and swagger is a set of tools to deal with openApi.
Source: https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/
Aside from swagger, there are a set of alternative tools like NSwag and Swashbuckle that can make working with the openApi specification easier.
There are 2 main parts:
Code generation for the openApi specification. You can generate code for the server (e.g. ASP.NET core rest controllers) from an OpenApi document and clients (e.g. C# rest clients, .TS rest clients, java you name it) from the OpenApi document. Or you can just generate the OpenApi specification (my SwaggerSpec.json) itself from e.g. your .net core project with some tooling.
(Web)Ui to easily host documentation. Swagger has webUI, NSwag, and even alternative tools like https://github.com/Redocly/redoc All of these include a way to easily test the Api endpoints you define. Generally these documentation sites are standalone things. They maybe configured style-wise but you generally leave them untouched. You can ofcourse roll your own - or clone any ui repos and alter that - but thats another topic.
I've investigated all 3 options (Swagger, SwashBuckle and NSwag) and i opted for NSwag because at the time a) it was the one i got working and b) it had the most features and c) the community was fairly active. This was about a year ago.
I shall explain my workflow and this should answer most questions you have. I feel like this Question is getting rather broad, so please do some digging around and try to get more specific questions tailored to your needs.
Like i said i use the NSwag toolchain:
I create Asp.Net controllers in my server app.
This contains some attributes to controller functions/endpoints so the swagger specification gets generated better:
I then use NSWag studio to create an openApi document file
Output:
At this point you could opt to use NSwag again to generate for example a typescript client which you can then use in your angular/react w/e frontend project:
I then add the swagger document to my asp.net server project, and enable the swagger UI:
Somewhere in Startup.cs:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IOptions<AppSettings> appSettingsAccessor, ILogger<Startup> logger, StaticFileConfigSection staticFileConfig)
{
// Add the openApi document and serve the swagger dashboard.
app.UseOpenApi();
app.UseSwaggerUi3(); // serve Swagger UI
...
And I can then go to /swagger to see the web ui:
And that's it. All these tools can be automated ofcourse - but i opted not to. Getting that to work can be a hassle and with NSwag studio i was always a button click away anyways. And this forced me to be more careful with my work.
Using Codegen is your choice. You can use the generated code as a boilerplate to have a straight start with your API integration. You may just copy the generated models and services and integrate them. It will save you a lot of coding time and also avoid human error in the coding of the services. But the rest of the frontend can be anything you like, not necessarily the generated project. You may use for example an Angular seed of choice and just integrate the services from Codegen.
As I've mentioned, you can copy the generated services and models from Cogeden, to have a head start. If you decide to go fully manual, you'll have to use Angular HTTP to make the requests to the server (https://angular.io/guide/http). You have to manually define the models and the services to operate with the entities. Swagger will only be a reference for the API in this case, no integration at all with Angular. I discourage this option unless the library generated by Codegen is insufficient. If the Swagger design is properly done (which sadly is uncommon to see), following all the standards and providing complete data models, you can trust the generated library.
This is advice and not objective guidance: if the updates to the API are minor, make them directly in your code and keep your Swagger updated with the new changes. If the changes are relevant, you need a new major API version, with a different endpoint. In that case, generating a new Swagger Codegen library and placing it in place of the old one will be a good idea. To be able to do this, you must avoid modifying the internals of the services of the generated library, using the library as much "as-is" as possible.
I have been working in the Django rest framework since three years on wards. Recently reading about FAST API frame work. FAST API looking like a very good framework for the current REST API service development. Seems like few things are missing from FAST API which are there in django.
Pagination
class based views.
mock testing
class based views.
struggled allot to provide the lookup for encrypted data in the django rest framework.
Could any one help me that how can we achieve above features with FAST API.
Currently in Jan 2020. FastAPI has a much smaller and different featureset to Django Rest Framework (DRF).
DRF is built on Django you have all the features Django available to you as well as convenient tools for building REST API's.
With FastAPI the framework way is more minimal it provides a simple, quick way to create and test a set of OpenAPI compatible endpoints. With a focus on speed and asynchronous style request-response handling.
However does not include ORM or migrations, admin, accounts etc and all the other 'batteries included' stuff you get with Django.
To achieve the functionality you have listed you'd right now you'd have to roll-your-own or use some pre-existing async python packages and adapt for your needs.
What's the easiest way to list all endpoints in Ratpack?
My app includes quite a few modules, so simply scanning Ratpack.groovy is not a good solution. Are there any existing tools to show all the exposed endpoints for the running app?
All routes are lazily generated; from everything that I've seen there isn't a way to do this. There was discussion back on March 10th on the ratpack slack channel about trying to do this for swagger document generation and that was the consensus. There's also an issue on github that hasn't gotten any attention for doing swagger generation.
I'd like to access some web api's using .net code, but am not sure if there's a way to generate a client side wrapper of some kind for these? Perhaps a code generator that can look at the web api documentation or through sample calls and generated .net classes and methods to encapsulate the api?
There isn't. REST-based APIs do not have a WSDL or service contract that could be used to generate a client stub.
That said, consider the following alternatives:
REST Coder: this is interesting research but no definitive tools yet.
Google for .NET WCF REST client: it turns up a lot of interesting results.
As far as I know, there isn't.
However, you can try one of the many wrappers available, that makes your life easier once you have to write less code.
Check this one out I've written a few months ago:
http://webapiclient.azurewebsites.net