top | item 39924142

Show HN: Extensible OpenAPI linter written in go

5 points| pb33f | 1 year ago |github.com

lint large and complex OpenAPI documents, build custom rules using JS or go.

3 comments

This is interesting but I'm curious what some of it means. For example, if I analyze the Kubernetes swagger spec [1] the tool gives it a quality score of 10% (terrible) and I'm curious why this score would matter or why spending time to improve it would matter

1. https://raw.githubusercontent.com/kubernetes/kubernetes/mast...

pb33f|1 year ago

the k8s spec is machine generated, it's a terrible example of a contract that is not used by anyone really.

The purpose of this tool is for companies that operate API first, the contract is curated and then code, docs and SDKs are generated from it.

Code first is generally a bad idea, it's often terrible and non human readable and creates terrible SDKs that break constantly.

API first is a contract first approach - which is where this tool comes into play.