3 ms·

I had these same issues. It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire A

I had these same issues. It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch.

haikuginger 10y ago
> I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch. Personally, I don't understand why codegen is even necessary as opposed to a pure object-oriented client that works directly from the Swagger spec. Before I knew Swagger existed, I actually implemented such a client based on my own made-up spec.[0] It's relatively naive, but I attribute that more to my relative youth in development than to the concept itself. [0]https://github.com/haikuginger/beekeeper https://github.com/haikuginger/beekeeper
cookiecaper 10y ago
>I had these same issues. It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. It's definitely going to be faster to just write it at first. Swagger, and everything like it, is an investment. >I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch. That's auto-generated code for you. Can't rival humans (yet), but that doesn't automatically mean it's not useful. Compare hand-rolled ASM with compiler-rolled ASM for an example. Human-written ASM will often be much more compact and readable, sometimes even more performant, but then you have to write ASM instead of letting the compiler do it for you.
eropple 10y ago
> It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. How long did it take to write API consumer libraries in twenty languages and update every one on API change? If you don't care about that, then Swagger isn't a good idea for you. But I'd think really hard about whether you should care about it if you think you don't. > the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch Sure--but you didn't have to write it.
- pbreit 10y ago
  Is whatever value people are getting out of client libraries provided by something generic like http://unirest.io http://unirest.io ? When does it make sense to issue API-specific client libraries for a plain ole RESTful API?
  - eropple 10y ago
    > When does it make sense to issue API-specific client libraries for a plain ole RESTful API? Any time you have a statically-typed language consuming you. Having to write my own Jackson declarations to pull in your API to a JVM project or my own DataContract barf for a CLR one is a quick way to make me hate you, and me hating you means I'm already looking for an alternative that isn't you that gets out of my way.
    - pbreit 10y ago
      I sort of thought the opposite, that the client libraries are what is getting in the way.
      - eropple 10y ago
        So you enjoy writing a bunch of boilerplate class files that are manual translations of somebody else's doc?
wing328hk 10y ago
> I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch. For Swagger Codegen, you can also customize the mustache templates in whatever way you want (e.g. replacing 4-space with tab in C# client templates). The auto-generated code may sometimes look lengthy but we usually do it with reasons based on feedback from developers. Please share with us more via https://github.com/swagger-api/swagger-codegen/issues/new https://github.com/swagger-api/swagger-codegen/issues/new so that we can further improve the output. You may find Swagger Codegen a huge time saver in use cases in which the endpoints are growing (e.g. from 20 endpoints in v1 to 40 endpoints in v2) and you will need to provide API clients in multiple langauges (e.g. Python, Ruby, PHP, C#, etc) Disclosure: I'm a top contributor to Swagger Codegen

haikuginger 10y ago

> I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch. Personally, I don't understand why codegen is even necessary as opposed to a pure object-oriented client that works directly from the Swagger spec. Before I knew Swagger existed, I actually implemented such a client based on my own made-up spec.[0] It's relatively naive, but I attribute that more to my relative youth in development than to the concept itself. [0]https://github.com/haikuginger/beekeeper https://github.com/haikuginger/beekeeper

cookiecaper 10y ago

>I had these same issues. It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. It's definitely going to be faster to just write it at first. Swagger, and everything like it, is an investment. >I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch. That's auto-generated code for you. Can't rival humans (yet), but that doesn't automatically mean it's not useful. Compare hand-rolled ASM with compiler-rolled ASM for an example. Human-written ASM will often be much more compact and readable, sometimes even more performant, but then you have to write ASM instead of letting the compiler do it for you.

eropple 10y ago

> It took me considerably more time and effort to write a Swagger spec and get the UI to actually behave than it did to write my entire API and some simple docs in markdown. How long did it take to write API consumer libraries in twenty languages and update every one on API change? If you don't care about that, then Swagger isn't a good idea for you. But I'd think really hard about whether you should care about it if you think you don't. > the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch Sure--but you didn't have to write it.

pbreit 10y ago
Is whatever value people are getting out of client libraries provided by something generic like http://unirest.io http://unirest.io ? When does it make sense to issue API-specific client libraries for a plain ole RESTful API?
- eropple 10y ago
  > When does it make sense to issue API-specific client libraries for a plain ole RESTful API? Any time you have a statically-typed language consuming you. Having to write my own Jackson declarations to pull in your API to a JVM project or my own DataContract barf for a CLR one is a quick way to make me hate you, and me hating you means I'm already looking for an alternative that isn't you that gets out of my way.
  - pbreit 10y ago
    I sort of thought the opposite, that the client libraries are what is getting in the way.
    - eropple 10y ago
      So you enjoy writing a bunch of boilerplate class files that are manual translations of somebody else's doc?

wing328hk 10y ago

> I also tried out the "codegen" and a few other projects that generate boilerplate from a spec (for Python) - the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch. For Swagger Codegen, you can also customize the mustache templates in whatever way you want (e.g. replacing 4-space with tab in C# client templates). The auto-generated code may sometimes look lengthy but we usually do it with reasons based on feedback from developers. Please share with us more via https://github.com/swagger-api/swagger-codegen/issues/new https://github.com/swagger-api/swagger-codegen/issues/new so that we can further improve the output. You may find Swagger Codegen a huge time saver in use cases in which the endpoints are growing (e.g. from 20 endpoints in v1 to 40 endpoints in v2) and you will need to provide API clients in multiple langauges (e.g. Python, Ruby, PHP, C#, etc) Disclosure: I'm a top contributor to Swagger Codegen