
Swagger is now the OpenAPI Specification - RyanZAG
https://buildazure.com/2017/10/20/swagger-is-now-the-openapi-specification/
======
rvanmil
Don't be fooled kids, this may sound great but it is in fact the gate to hell.
Back when I was young the same thing was called SOAP and it also promised
standardized APIs in a vendor neutral description format and code generation.
It was pure misery. I still have nightmares about it. They may say they only
bring the good parts of SOAP, but there are no good parts in SOAP.

~~~
duskwuff
The Swagger/OpenAPI spec format is its own special little hell. Just enough
"user friendly" features to make it difficult to parse, yet still complicated
enough that it's a pain to write.

~~~
hobofan
I thought I was the only one! As far as I can tell the sentiment regarding
Swagger/OpenAPI is generally positive, but I am starting to think that's just
because it's an improvement over the status quo of "nothing" for most people.

I personally prefer API Blueprint, but even there is room for improvement.

~~~
bjz_
I prefer RAML tbh - using Markdown as the basis of an API specification
language is a pretty terrible idea. RAML's syntax is much more structured and
pleasant, and the type syntax is far nicer to write than JSON Schema. Alas it
seems to have lost the battle of network effects...

------
OJFord
I'm very confused, the article bills this as news, but this has been true for
at least a year, is the news that v3 is now 'current' rather than in
development?

[https://github.com/OAI/OpenAPI-Specification](https://github.com/OAI/OpenAPI-
Specification)

~~~
sb8244
I believe you're correct. It hasn't been official yet despite being mostly
ready to go

------
czardoz
I always found Swagger to not be very readable or usable. APIs keep changing,
and are meant to be malleable, not rigid. IMO, Swagger always ends up being
too much planning, too little implementation.

I remember having a bunch of discussions about these issues when I worked on
the Postman Collection Format ([https://github.com/postmanlabs/postman-
collection/blob/devel...](https://github.com/postmanlabs/postman-
collection/blob/develop/examples/collection-v2.json)) which can be very
flexible.

------
pkamb
The one Swagger docs site my team used, we all thought it was completely
broken for the first several weeks of trying to access it.

Turns out there was a small red ("error" colored...) header bar near the top,
collapsed by default. You need to click that to expand out all the API docs.
Fun design.

------
pritambarhate
Which editor do you use to edit Swagger? Writing Swagger specification by hand
is a nightmare because of the poor online editor. The error messages are hard
to understand.

Also Swagger.io people decided to replace the old editor with the new editor
and it doesn't have many useful features the old has. Thankfully they kept the
old one live.

Swagger is not all that hard to understand. This is a fantastic tutorial which
helped a lot to get started: [https://apihandyman.io/writing-openapi-swagger-
specification...](https://apihandyman.io/writing-openapi-swagger-
specification-tutorial-part-1-introduction/)

------
patkai
Is there a good writeup on "WSDL: Lessons learned", with some depth?

------
pixie_
Is there any standard as to how to do some of these thing - API versioning?
actions like login/logout? doing a GET on multiple IDs? spinal casing? common
response object format? application specific error codes?

~~~
quicklyfrozen
The spec allows you to describe how you decide to implement these things; it
doesn't proscribe any particular API patterns.

You can declare types separately from APIs to make your last two items easier.

------
Kpourdeilami
Another API specification that I really like is
[CoreAPI]([http://www.coreapi.org/](http://www.coreapi.org/)) .

It works nicely with the django-rest-framework (both created by the same
person) and has clients for python, javascript, and a command line tool to
interact with the API. I have written a small python script that takes our
CoreAPI specification and then generates markdown documentation around it.

The catch is that it is not as well documented as Swagger so working with it
would require digging into its source code.

------
michaelbryzek
API Builder [[https://www.apibuilder.io](https://www.apibuilder.io)]
integrates many of the end to end tools teams need to manage APIs at scale.
JSON remains first class and support for swagger is native (also supports avro
idl… protobufs to come).

API Builder was started in 2014 as a free and open source project to build a
community around best practices we learned scaling gilt.com and building
flow.io.

Managing great APIs end to end at scale and over time take a huge investment
in culture and tooling. API Builder solves a number of those problems.

A few reasons why teams adopt API Builder.

\- Very, very high quality generated clients: Teams that use API Builder end
up relying 100% on the generated clients - ie. the developers STOP writing and
managing their own client SDKs, freeing up time to focus on product
improvements.

\- History: Every change in spec is documented - accurate and automatic - e.g.
[https://app.apibuilder.io/history?org=apicollective&app=apib...](https://app.apibuilder.io/history?org=apicollective&app=apibuilder-
spec)

\- Resource centric: API Builder is resource first - instead of defining an
operation explicitly, you define resources and then expose operations on that
resource.

\- Simple service specification: API Builder at its core separates the notion
of the input format (e.g. api.json, swagger, avro) from the service
description (service.json). This is a huge advantage: regardless of input
format, the service specification can be fully expanded and complete.

\- Simple input format: The default api.json format is simple for humans to
write. It is JSON, but more than that it is approachable by a novice and
designed to be both simple and easy.

\- Easy to add code generators: Code generators in API Builder are themselves
REST services which accept a service description (in JSON) and essentially
return a string. Teams often write their own code generators - even small
disposable ones - to systematically solve problems in an automated fashion.

\- Testability of clients: With generated mock clients built from the same
interface definition, teams can rely on mocks when building automated tests -
and further use the provided mock clients to override only the specific
features needed for a given test.

\- Workflow that works with micro or mono repos and allows for concurrent,
branched development of spec, service and client

More at [https://www.apibuilder.io/](https://www.apibuilder.io/) and
[https://app.apibuilder.io/doc/why](https://app.apibuilder.io/doc/why)

[edit: formatting]

------
tschellenbach
I don't see how Swagger helps me build, document or test my API. Anyone have a
good experience to share?

~~~
zamalek
So far as documentation goes, OpenAPI does include fields for human
consumption - such as "example". I've been using Swaggerhub to validate my
OpenAPI documents and it clearly demonstrates what the automatically-generated
documentation might look like.

It won't help you at all with unit testing (you shouldn't be using HTTP for
that). You can theoretically use it to generate a client library in your
language of choice for integration tests (true for Swagger, not yet for
OpenAPI). Finally, there are tools built around it that let you play around
with APIs that have these specs - Microsoft PowerBI comes to mind.

There are ways you could use it to build an API, but I wouldn't consider them
a good idea. Edit: You could completely automate the process of ensuring that
your semantic versions are compliant (i.e. you aren't breaking compatibility
when you are claiming that you are not).

------
jimmcslim
Do Swagger/OpenAPI and its more popular implementations support JWT/bearer
tokens yet?

~~~
quicklyfrozen
The spec seems to:
[https://swagger.io/docs/specification/authentication/bearer-...](https://swagger.io/docs/specification/authentication/bearer-
authentication/)

I'd be curious about implementation support as well. I was able to get it to
work with earlier versions, but IIRC it involved using the apiKey in header
auth type and manually adding "Bearer" to the auth header.

------
anon335dtzbvc
Still the best option is the unix philosophy: "Write programs to handle text
streams, because that is a universal interface." \- Peter H. Salus in A
Quarter-Century of Unix (1994)

~~~
deathanatos
It really isn't the universal interface. At some point, most of us need to
transfer more than just "text", even if we end up representing the data as
text. For example, if I need to describe the name, breed, and sex of a set of
dogs, I can transfer that as JSON:

    
    
      [
        {
          "name": "Spot",
          "breed": "Dalmatian",
          "sex": "male",
        },
        ...
      ]
    

as CSV:

    
    
      name,breed,sex
      Spot,Dalmatian,male
    

etc. The list goes on. The concept of "text" fails to capture both the higher-
lever format (JSON, CSV) and the lower-level details (what the keys are in
JSON, what values might be valid for enumerations such as "sex", etc.; what
units for numeric types, how do we represent null (esp in CSV), etc.).

For JSON HTTP APIs, Swagger makes a not-that-bad (IMO) attempt at describing
the format of the structure.

The Unix philosophy, while it works well in _specific_ cases, does not lend
itself well to the creation of robot solutions. Parsing text streams with
tools like sed/grep which are not the right tool for the job, in that they
cannot understand the corner-cases of JSON/CSV/etc., leads to brittle
solutions. (e.g., a use of sed/awk on the above CSV might work, until we get a
more complicated format in a later iteration with a field containing an
embedded newline, and our awk script falls down b/c we're not using a real CSV
parser.)

