Open andyws opened 7 years ago
As a follow-up I have loaded a local copy of the application raml into apiworkbench. I get the following errors:
Can not resolve http://api-documentation-raml-frontend.service/api-documentation/assets/common/docs/versioning.mdat line 13 col 4
Error
Can not resolve http://api-documentation-raml-frontend.service/api-documentation/assets/common/docs/errors.mdat line 15 col 4
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/securitySchemes.raml'at line 18 col 3
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/headers.raml'at line 19 col 3
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/annotations.raml'at line 20 col 3
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/types.raml'at line 21 col 3
I wish to use the raml to auto-generate client and test stubs. how would you suggest I proceed?
I feel that even though this is a fairly simple api there is a total lack of context contained in the documentation. By ‘context’ I mean items such as:
Narrative explaining how the api is to be exercised, ie the various scenarios/use cases which the api is supposed to satisfy.
Interaction diagrams which underpin the above in a more systematic way.
Hi,
At the moment the RAML is only used internally, for example the documentation you can view is generated from it.
Since it is internal there is no public URL and it contains references to other internal URLs which is why those links can't be resolved and you can't easily use it to auto-generate client and test stubs.
We may publish RAML in the future, Alex Browne (API Platform Product Manager) is probably a good person to ask about that.
My experience with the creation and implementation of APIs leads me to expect that development should be led by using a spec ( RAML / Swagger ). This should include not just the implementation team but also the consumers of an API.
I've let the API Platform team know about this github issue because whether we publish RAML is likely to be decided on a platform-wide basis.
Ok. Out of curiosity do any of your team see it as unusual to do API development whereby a spec ( RAML / Swagger ) is used to unambiguously communicate an api and allow the automatic and thereby less defect prone generation of boilerplate code on both the client and server?
What is the RAML Url for the beta api?
Do you use the RAML to auto-generate client/server code/documentation?