Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Open API Initiative

openapis.org

Post reply on HN
Print view View original

11–20 of 23 posts

Re: The Open API Initiative

#11

Post by palakchokshi »

yeukhon wrote: post #10

The real major Open API I always think is required is an Open API allow me to interact with any part of a website so people can finally build assistive technology based on API rather than parsing some website's DOM that you will likely never be able to parse out correctly from version to version. If the website exposes a "REST" specification how to interact with the pages, then we can really build a website visual im…

What you are looking for is the semantic web or an accessible web. There are standards to create an accessible website but few developers do it unless their market has a significant number of visually impaired people. This is further complicated by Single Page Applications and/or web apps. If there was a browser extension or something that made every website accessible that would be an awesome extension.

Re: The Open API Initiative

#12

Post by palakchokshi »

porpoisemonkey wrote: post #8
whatnotests wrote: post #6

What most API documentation lacks is one thing. Examples. Real, working, copy-n-paste examples. While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation. Sure, schema helps, but having a spot to just lay out an example request or response is really important. Another thing: often, one must perform prerequisite steps…

There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/exa...

I believe he meant a way to put examples in the spec itself. I believe they have a client SDK that will consume the API spec and allow you to make requests and see responses.

Re: The Open API Initiative

#13

Post by porpoisemonkey »

palakchokshi wrote: post #12
porpoisemonkey wrote: post #8

Earlier quoted context omitted.

There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/exa...

I believe he meant a way to put examples in the spec itself. I believe they have a client SDK that will consume the API spec and allow you to make requests and see responses.

Ah I see. The OpenAPI specification for the interface description language and the auto-generation tools are actually two separate entities so I'm not sure it would make sense that they put examples for a specific auto-generation tool in the official OpenAPI repository.

It seems like the best supported tool for generating client and server stubs is Swagger Codegen. Version 2.1.2 seems to support the OpenAPI 2.0 draft spec.

http://swagger.io/swagger-codegen/

http://swagger.io/getting-started/

Re: The Open API Initiative

#14

Post by sinzone »

palakchokshi wrote: post #5

Next will come the API spec parsers to automate client code generation. Those will break on the first vendor specific extension. Vendors will put in extensions for security, pre and post request action guidance, etc. This will cause vendor specific client code generators to be created. The specification will take a long time to get updated as each vendor will want their extensions in the core specification. As a resu…

Already happening. Tools (like https://gelato.io) provide auto-generated docs, live test-console, code snippets and SDKs from your Swagger file. It comes with a free plan for OSS projects.

Re: The Open API Initiative

#15

Post by bbrennan »

whatnotests wrote: post #6

What most API documentation lacks is one thing. Examples. Real, working, copy-n-paste examples. While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation. Sure, schema helps, but having a spot to just lay out an example request or response is really important. Another thing: often, one must perform prerequisite steps…

Having a machine readable spec is important for driving examples though. For instance, at LucyBot we use OpenAPI to drive Recipes - tutorials for using an API to achieve a specific use case. Each recipe provides working sample code in a few different languages. You can see examples for Kaltura's video API at developer.kaltura.org

Re: The Open API Initiative

#18

Post by whatnotests »

porpoisemonkey wrote: post #8
whatnotests wrote: post #6

What most API documentation lacks is one thing. Examples. Real, working, copy-n-paste examples. While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation. Sure, schema helps, but having a spot to just lay out an example request or response is really important. Another thing: often, one must perform prerequisite steps…

There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/exa...

Yes, I mean documentation in general.

It's fine to just show a long list of method signatures and class hierarchies, but a working code sample is the picture that's worth a thousand words.

Re: The Open API Initiative

#19

Post by progx »

whatnotests wrote: post #18
porpoisemonkey wrote: post #8

Earlier quoted context omitted.

There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/exa...

Yes, I mean documentation in general. It's fine to just show a long list of method signatures and class hierarchies, but a working code sample is the picture that's worth a thousand words.

You mean something like this:

http://apidocjs.com/example/

generated from this

https://github.com/apidoc/apidocjs.com/tree/gh-pages/source/...

Re: The Open API Initiative

#20

Post by JimDabell »

Does anybody have any recommendations for a Swagger-style documentation toolchain for REST APIs? I mean actual REST, not this weird anti-REST where you predefine fixed URI structures up front.

REST APIs are based around media types, not URI structures. Unfortunately, tools like Swagger are based around URI structures, which shouldn't be in REST API documentation at all. It makes trying to find good tooling for REST APIs difficult when people say "just use Swagger" and similar.

Post reply on HN