Unfortunately, actual usability seems to be getting ignored in the rush for a "standard". In the meantime, you might want to consider using RAML. It compiles to

Unfortunately, actual usability seems to be getting ignored in the rush for a "standard". In the meantime, you might want to consider using RAML. It compiles to OpenAPI and is far more optimized for use by humans instead of machines.