Add `logo` as root parameter

raml-org / raml-spec

RAML Specification

http://raml.org

3.87k stars 857 forks source link

Add `logo` as root parameter #127

Open aldonline opened 10 years ago

aldonline commented 10 years ago

RAML documentation generators can then use this parameter to generate customized documentation. This would benefit API developers and consumers.

#%RAML 0.8
title: My API
version: v3
logo: http://example.com/logo.png

Suggested dimensions: 300px square.

The square makes it easy to use the logo both vertically and horizontally.
The square format is an industry standard. Initially for user avatars but more and more sites require the format for companies as well ( twitter, facebook, github, angel list, etc )

kevinrenskers commented 9 years ago

I'd really like this feature too. Or actually something like #110, which would allow unlimited metadata for something like raml2html and other parsers / tools.

sichvoge commented 9 years ago

@aldonline should that be part of the 1.0 milestone?

dmartinezg commented 9 years ago

This is metadata, and not functional, I agree with @kevinrenskers, this should be in #110

sichvoge commented 9 years ago

For me, the difference between metadata and having it inside the RAML spec is that common information are not standardised. One could call it logo, someone else image or companyLogo. There is no commonality between them which makes it very hard to use tooling for API discovery for example. Don't get me wrong, but I see metadata more commonly used inside organisations which needs specific information to be inside their spec, but it makes it harder for making the API description itself public and develop common tooling on top of it.