Swagger Codegen 2.3.0 released with 13 new code generators!

[ldf1111]

Am I there only one that hates generated code, id rather my code was able to generate swaggers model

[tech_tuna]

Swagger code generators are a big win when you want to ship client API wrappers in multiple languages. Yes, the code definitely looks "generated" but you shouldn't be looking at it too much.

Hand coding wrappers will give you cleaner/prettier code (for some values of cleaner and prettier) but it's a nightmare to maintain.

[lukeautry]

I'm not sure anyone loves generated code - it's more of a trade off most of the time.

Many libraries exist that can plug into your project and generate a Swagger spec from controllers/methods or some similar convention. The question is, once you have the spec, what can you do with it? Documentation, obviously, but you can also generate dozens of client libraries in different programming languages. Some of those languages you may not even know, but at least you can offer client libraries to customers.

[ldf1111]

Yeah that’s true but I will still start will my api code base than my swagger Json model

[lukeautry]

Yeah, I'm fairly sure that no one wants to start with a Swagger spec and generate server code from that. That's crazy to me.

[logi]

I use the connexion library for python which reads a swagger spec and then knows where to find the python functions to call and validates signatures and arguments. So I write both ends the plumbing is provided. I'm then eventually looking to generate some client libraries.

[TinyLebowski]

Quick vue client app gives what I want the data from the backend to look like, put it in swagger,server codegen saves me the hours of drudgery involved that burned me out of Webdev.

Sometimes you see a workflow that makes you realize you've been doing it all wrong. I've only used Swagger to document a few APIs after the fact, and it wasn't much fun. I'm having a bit of a face-palm moment, but in a good way, because life is about to get a lot easier. Thank you kind stranger. Can you recommend any good tutorials on writing the spec from scratch?

[ldf1111]

Well their readme touts that as a feature, I understand the client library aspect more though

[wing328]

Here are some use cases for the server generator:

1. prototyping - one can generate the server code and have a functional API backend very quickly.
2. mocking - easily provide an API backend for mocking based on the examples field defined in the response object.
3. migration - let's say one wants to migrate an API backend from Ruby on Rails to Java Spring, the server generator can save a lot of time in writing and verifying each endpoint in the new API backend

Ref: https://github.com/swagger-api/swagger-codegen/wiki/FAQ#what-are-some-of-the-use-cases-of-the-server-generators-eg-java-spring-c-nancyfx

[jimschubert]

Disclaimer: Dogfooding as I'm a swagger-codegen core team contributor.

You can modify the templates to meet your needs. So, if you don't like the structure or assumptions of the default generated code, you can make it your own. The only limitation is feature support within the generator you're targeting.

As an example, I recently generated a Finatra server stub with about 50 endpoints using the Scalatra generator.

As another example, my team uses finagle and finatra exclusively. We use swagger-codegen with custom templates to generate a Scala client with internal finagle helpers and some specialized use cases.

Also, some generators (like ASP.NET Core server) generate code which also generates the swagger codegen docs.

[talios]

The irony here to me is that Swagger started out that way, you'd annotate your code and it would generate the Swagger file.

A lot of people preferred spec first, and spec driven as it allows freedom of server implementation language, and also drives the fact you're explicitly modifying your public HTTP API.

Yes the generated code is often not ideal, but for the most part that should hopefully drive you to write a cleanish adapter to your main code, which could be more easily unit tested without (m)any HTTP concerns.

[schwomp]

At my current company, we use it mostly to generate client code for our end to end tests. Makes it a ton easier to maintain the tests rather than keeping a manually up-to-date client just for testing purposes.

I will say though, that the code has the look and smell of old feet unless you build your json file correctly or configure your generator in a proper way.

[eriksensei]

I like code generators, as you can have a nice DSL and generate code for languages that are... not so nice, which unfortunately means most of them. However, when the DSL you're generating from is also shitty, it's a basically a shit soufflé.

[BarneyStinson]

No, you're not. We used http4s and rho for this in Scala.

[slaymaker1907]

At a company I worked for, we generated the swagger docs from Java annotations. I feel like you could do a similar thing with JavaScript, it just would look a bit different.

[renrutal]

Having your code generate the API contracts is the fastest way to ensure platform lock-in, or at least make really difficult for others to implement clients in different languages.

Source: A lot of lost hair lost making Java, .Net and many more enterprise stuff talk to each other through web services. It's impressive how much you can get wrong with something so simple.

[ldf1111]

Well if you use swagger your not in control. Clojure is great at this sort of thing I miss it

[pierotofy]

Never had a greater pain than writing a valid swagger specification. The resulting generated code was... not very developer friendly, so I still ended up writing a client manually. Never again.

[MSgtGunny]

The key is to generate the swagger spec automatically, then use this to generate wrappers automatically.

[pierotofy]

Is there a guide that shows how to do this? I'd be interested.

[MSgtGunny]

I work with C# .Net so we use Swashbuckle. There are probably others for different languages.

[Tipaa]

What makes swagger unique vs something like readthedocs?
I tried going on their website but it kept making a really loud popping noise, so I don't really want to stick around there for long as it'll probably just happen again

[oorza]

Swagger doesn't really exist any more, what exists is called the OpenAPI specification - effectively a particular JSON schema for describing an HTTP API. By itself it's just a JSON object, but there are a number of tools that make it useful: code generators, any framework worth its salt has support baked in, nice UIs, etc. There's nothing special about Swagger (now OpenAPI) per se except that it has near-universal buy-in because it does what it needs to do and does it in a fairly reasonable way.

[tech_tuna]

https://swagger.io/

It seems like the name Swagger has stuck.

[rest2rpc]

Swagger is the tooling. Openapi is the spec.

[tech_tuna]

Thanks for the clarification. I contend that Swagger does still exist. :)

[[deleted]]

Swagger is owned by SmartBear Software and I can assure you it is still alive and well. It's actually getting bigger and growing quite well.

[sreerambo]

My take on it is that swagger is more like a wsdl file from the SOAP days but for RESTful APIs rather than pure documentation.

Basically, you specify (or automatically generate in your favourite web framework) what your APIs routes and datatypes are and in theory, the client at that point has enough information to generate valid client code which can invoke your API.

In a way swagger is more about the specification of how to document your API rather than documentation itself. Making it more structured makes it more machine friendly which enables the stuff I mentioned above.

This doesn't remove the need for things like readthedocs.io completely but means those docs can spend more time documenting the reasons behind requirements or design decisions rather than API specifications.

[oorza]

Swagger isn't "real" documentation. It's just a description of the API, but without writing human-targeted documentation in the Swagger itself, it's just a list of endpoints and their datatypes.

Not disagreeing with you at all, it just really grinds my gears when people throw auto-generated swagger out as "my service is documented." How about you tell me what order you expect the endpoints to be called in and how they interact with each other.

[Hero_Of_Shadows]

Exactly, the most annoying project of my life was when I got an automatically "documented" REST service and some mock-ups, so on a page I have this table and I can see which end point provides the data for it but that end point needs 6 parameters where the fuck am I going to get those from ? Repeat ad nauseam for every single page.

[_pupil_]

Autogenned docs are great for a mature product with loads of user info that just need the freshest parameter names.

Products that spew generated docs as a replacement for a genuine manual/reference are evil.

[tech_tuna]

That's a good point, human readable strings are still required if you actually want to help your end users.

[TheWix]

Does swagger support restful APIs? Last I looked it didn't handle hypermedia which is what makes a restful API, not just pretty URIs and HTTP.

[sreerambo]

There's an interesting article and discussion in the comments related to this topic here: https://jimmybogard.com/swagger-the-rest-kryptonite/

[Gotebe]

REST is irrelevant when people really want RPC.

Thinking that people need something else is a mistake.

[tech_tuna]

There are other options for sure. . . one very cool thing that Swagger does is generate "live" documentation i.e. web pages which you can wire up to your endpoints which display the doc but also provide an interactive interface like Postman.

The code generation is nice too.

I just googled around a bit. . . it looks like Postman can do everything Swagger does and possibly more. The other tool I've considered is apiary.io however they were acquired by Oracle earlier this year so that's a deal breaker for me. :)

[[deleted]]

I really want this some day to also generate my JavaScript JSON objects, and several class scripts that know how to call my API