search

raml-org / raml-spec

RAML Specification
http://raml.org
3.87k stars 858 forks source link

Custom properties from RAML very important for a parser #638

Open pakkk opened 7 years ago

pakkk commented 7 years ago

Hello,

I was wondering if RAML could add custom properties. If so, I think it could be a good way to follow a specific prefix to define all of them, like SWAGGER does (i.e. specify any prefix like 'x-' to see every custom property quickly because all of them start with 'x-').

On the other hand, I think that it would be useful to have an unique identifier 'operationId' like SWAGGER define to identify every endpoint/operation, for example:

...
/myEndpoint:
  get:
    operationId: myOperationIdGet
    ...
  post:
   operationId: myOperationIdPost
...

I am developing a RAML parser to have different output languages/frameworks like 'Spring MVC', 'Angular2', 'JAXRS', 'Feign', etc. and I think it is very important to have a unique identifier for all the available operations.

You can visit the following GitLab project to understand my concern:

https://github.com/BBVA-CIB/APIRestGenerator

Many thanks.

Regards, Paco.

sichvoge commented 7 years ago

Have you had a chance to look at RAML Annotations. I do think it is what you are looking for.

pakkk commented 7 years ago

Thanks Christian :)

But...don't you think it would be useful to have an "operationId" as official/compulsory property for all the endpoints/operations?

Regards, Paco.

sichvoge commented 7 years ago

IMHO, operationId used for code generation is a very special case for specific tools to understand and act upon on. It does not have anything to do with your actual API and isn't important for your consumer. I would try to strictly separate information that are needed for specific tools.

That's why annotations are so powerful. They introduce that separation.

The crew and I are actually working on some "RAML community approved" annotations. For example, some that we have been implemented in raml-for-jaxrs will go into that repo.

BTW, I really like you profile picture - go superstars! ;)

pakkk commented 7 years ago

Thank you for your perfect explanation ;)

Yes, operationId is a powerful attribute to distinguish every endpoint/operation, but I understand what you are referring to. Then, I will use Annotations ;)

And...yes, it is a pain Oliver Atom did not like the computers, imagine his skills applied to programming languages :P