Stream: implementers
Topic: Swagger and RAML
Grahame Grieve (Nov 03 2016 at 06:06):
I've done some preliminary work on creating swagger output as part of the IG publisher. And I see that Swagger haev now created
Grahame Grieve (Nov 03 2016 at 06:06):
'The OpenAPI foundation'
Grahame Grieve (Nov 03 2016 at 06:06):
but I've found Swagger to be... overly simplistic about the content
Grahame Grieve (Nov 03 2016 at 06:07):
Another implementer has been investing in using RAML - it seems deeper and more sophisticated, but doesn't seem to have quite the community behind it
Grahame Grieve (Nov 03 2016 at 06:08):
I could adopt/adapt that work, and make producing documentation by RAML a base function of the IG Publisher. I don't appear to have the same option for swagger; it doesn't give me quite the same control points (or it didn't last time I looked).
Grahame Grieve (Nov 03 2016 at 06:08):
Does anyone want to express any opinions about swagger and RAML?
Stephen Royce (Nov 03 2016 at 06:16):
Apparently NIO have had a few queries for both. @Shovan might be able to give you more details.
Grahame Grieve (Nov 03 2016 at 06:25):
I wasn't going to call out @Shovan Roy in public yet, but he's the 'another implementer' and I had a good look at what he's doing yesetterday
Stephen Royce (Nov 03 2016 at 06:49):
Whoops. Sorry! 
Joel Schneider (Nov 07 2016 at 21:51):
$0.02: I'd be interested in a swagger definition of the terminology service api. Haven't really looked at RAML yet, partly because my organization currently favors swagger. If Swagger is overly simplistic, maybe workarounds involving OpenAPI.next issues or pull requests could be developed.
Grahame Grieve (Nov 07 2016 at 22:38):
I'll work on a swagger for terminology
Anand Mohan Tumuluri (Nov 08 2016 at 22:19):
I am an employee of another organization heavily favoring Swagger and had the horrible pain of developing and reviewing a Swagger model for our API supporting ~35 FHIR resources. Short answer is that, even after employing the most reuse(parameters, responses, etc), the resultant model does not work with any tooling, (Swagger Editor Online, Swagger offline codegen, etc, etc). It was just a painful, unwieldy beast. In comparison, the RAML model for FHIR (from googling) seems a lot more cleaner. However, I am extremely new to RAML itself, so dont have an opinion for/against it.
Grahame Grieve (Nov 08 2016 at 22:20):
what are the causes for it not working?
Anand Mohan Tumuluri (Nov 08 2016 at 22:20):
The tooling just hangs which kind of loses the point of having API documentation generated.
Anand Mohan Tumuluri (Nov 08 2016 at 22:21):
After removing some of the API paths/resources, it was working fine.
Dennis Roche (Nov 09 2016 at 07:11):
Can you clarify how Swagger was over simplistic about the content?
nicola (RIO/SS) (Nov 09 2016 at 09:00):
I think, swagger is more perspective - https://www.openapis.org/
Grahame Grieve (Nov 19 2016 at 17:23):
Follow up on this - we had a session on this at DevDays. There were quite a few people present for it - perhaps about 50 - and there was pretty strong consensus around 3 things:
- implementers would like to be able to produce processible definitions for FHIR end-points using a cross-industry standard
- Swagger is such a thing, and RAML is not (whatever it's technical advantages might be)
- Swagger appears able to describe a FHIR interface fully, but we will investigate exactly how well it supports slicing
Sorry, @Shovan, swagger is the go
Shovan (Nov 20 2016 at 03:35):
Thanks @Grahame Grieve Thanks for taking it to the DevDays . May I request a sample Swagger file?
Grahame Grieve (Nov 20 2016 at 05:23):
Grahame Grieve (Nov 20 2016 at 05:28):
Has anyone done a swagger for a Smart on FHIR server?
Kevin Mayfield (Nov 20 2016 at 10:23):
Yes but not automatically. We've been using Apache Camel + Swagger (http://camel.apache.org/swagger-java.html) in front of local HAPI servers and national systems as part of the Implementation Guide. I intending to keep it a manual part of the documentation process (API documented in Camel alongside the internal profiles).
Alexander Henket (Nov 21 2016 at 21:20):
I picked up from the Vimeo video what you guys were up to and got inspired to look into Swagger. I don't get at all how you connect content descriptions but I'll find out eventually. Just wanted to post this link to v3.0 that is underway apparently: https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md
I asked in the google group whether or not they have a defined way of finding out if service X has a Swagger definition or not. The answer was that they are thinking about adding that for v3.0 and leaning towards an Accept header with a defined mime type. Translating that to FHIR I suppose that this is reasonable:
[base]/metadata?_format=application/x-yaml+swagger
Exact mime type tbd (found this one here http://stackoverflow.com/questions/332129/yaml-mime-type#332159)
Grahame Grieve (Nov 22 2016 at 04:27):
that would work for us
Last updated: Apr 12 2022 at 19:14 UTC
