Stream: implementers
Topic: openAPI
nicola (RIO/SS) (May 06 2017 at 12:12):
I've contacted OpenAPI guys - they are open for collaboration - i think, verification & harmonisation of FHIR/swagger/JSON-schema by OpenAPI - would be very valuable. @Grahame Grieve ?
Grahame Grieve (May 06 2017 at 12:55):
sure, we like to collaborate. Can you hook me up with them by email?
nicola (RIO/SS) (May 07 2017 at 06:29):
Yes
Grahame Grieve (Feb 06 2018 at 00:10):
@Josh Mandel have you looked at openAPI to see how Smart on FHIR would be represented?
Josh Mandel (Feb 06 2018 at 00:11):
I'm not sure I understand the question -- OAPI doesn't include a language for modeling OAuth profiles, does it?
Josh Mandel (Feb 06 2018 at 00:11):
I mean, you can certainly annotate endpoints with "needs xyz OAuth scope"
Josh Mandel (Feb 06 2018 at 00:12):
And you can advertise your auth/token URLs
Josh Mandel (Feb 06 2018 at 00:12):
Is that extent of what you have in mind?
Grahame Grieve (Feb 06 2018 at 00:12):
no it does have a language. here's a sample:
Grahame Grieve (Feb 06 2018 at 00:12):
{ "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } }, "authorizationCode": { "authorizationUrl": "https://example.com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/token", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } }
Grahame Grieve (Feb 06 2018 at 00:48):
And a different question, for a more general audience: we cannot describe our XML format in openAPI because of the way they describe XML - as a variant of JSON. What we can't do is deal with extensions
Grahame Grieve (Feb 17 2018 at 20:14):
@Josh Mandel ping on this
Aaron Seib (Feb 18 2018 at 00:02):
This is very interesting from the perspective of being able to transport Consent resources. I have much more to learn but the problem I am working on is can be summarized as follows...
I am a consumer and want to capture my privacy preferences in one place so that it is easy for me to update it. At the last CCDE connectathon we were able to demonstrate how a Consent Resource could be created in a Consumer Controlled App and subsequently shared with a central service that uses it to make disclosure decisions on my behalf.
The problem we discovered was that it was a challenge to verify that the scopes supported by the central service matched what I perceived to be my preferences in the Consumer Controlled app. It was not really a problem for the trivial cases of all in or all out but once we started getting more granular there wasn't a way for me to verify that the system I was pushing my preferences to had the Scopes in place to support the preferences I had documented. We can address this via Trust Frameworks (Policy) but I keep searching for a way to establish more standard scopes for this use case.
It seems like some preferences would be implementable this way while others may not. It comes down to whether or not we have common standard values or identifiers in most cases. For example - if I create my privacy preferences in my Consumer App and indicate that I don't want to share anything with Dr. Who - if my CCA and the Central Distribution system don't have the same Identifiers for Dr. Who even though I may be able to migrate my Consent Resource to the central system it won't be able to respect my privacy preference with regards to Dr. Who unless we are both using the same Provider Registry.
As I am sure your aware - there is a lot of interest in figuring out if we can apply standard security labels on behalf of the consumer. Assuming there was a way to indicate which SLS you were using and that the SLS used to set the consumer's preferences were the same as the one used in the central service we could define standard scopes consistently and as a result be able to transfer a Consent Resource from the CCA to the central system and expect that it could make sharing decisions on the consumers behalf.
So - after laying all that out my question is do you think we could employ this OAI as a way to convey privacy preferences in a Consent resource and have a computable way to verify that the central system can support the same scopes I perceived I was authorizing in the first place?
Roberto Polli (Mar 26 2018 at 15:18):
Hi everybody!
Is there an ongoing work on OpenAPI representation for FHIR services?
Thanks,
R.
Grahame Grieve (Mar 26 2018 at 19:06):
the IG publisher produces openAPI documents for any CapabilityStatements it sees. But that's very new and still beta and hasn't made it's way into any published IGs yet, and nor is the tool available for other use yet (I haven't packaged it yet)
Roberto Polli (Mar 27 2018 at 12:48):
Hi @Grahame Grieve and thanks for your reply!
So, if I understood correctly, there's this tool http://wiki.hl7.org/index.php?title=IG_Publisher_Documentation#Publishing_Implementation_Guides that can present openapi specs for the various CapabilityStatements but the openapi part is still WIP, right?
Is there any git repo where I can check the implementation?
Thanks again!
Grahame Grieve (Mar 27 2018 at 12:53):
all the source is in svn, in https://gforge.hl7.org/svn/fhir/trunk/build, the java package org.hl7.fhir.igtools.openapi
Øyvind Aassve (Aug 13 2018 at 09:58):
Hi all,he Norweigan government is working on a cross-sectorial API-catalog where they plan to publish an extensive part of public sector APIs for external access. One of the primary goals with this is to facilitate industry contribution to business development, innovation and improvements in public sector. Health quality registry APIs are considered as a possible early candidate for publishing in the catalogue.
The work so far has been considering the openAPI specification as the common representation format for publishing these APIs across all public sectors.
The question is: I know there are some work on the way in representing FHIR profiles/ conformance statements in the openAPI-specification format. But could it in this context be a better alternative to represent health care APIs directly on FHIR also in a national cross-sector context? What could be possible issues to consider if transformation to openAPI are chosen as the preferred alternative? Any thoughts or experiences?
Grahame Grieve (Aug 13 2018 at 10:44):
openAPI is much more comprehensive that FHIR on web access / security. We won't be taking that space on, since they have.
Grahame Grieve (Aug 13 2018 at 10:45):
openAPI will never be as thorough as us about the content model that is being exchanged. They'll use JSON schema which is a subset to various degrees of what FHIR says (there's some proposals to extend JSON schema to the infinity to say what we say, but I don't really see the point).
Grahame Grieve (Aug 13 2018 at 10:46):
in the API specification we say things they don't say and vice versa. I may get a chance to attend an OpenAPI meeting and see if we can get some reconciliation on that - it seems as this difference is more accidental than justified or deliberate
Grahame Grieve (Aug 13 2018 at 10:47):
it I were you I'd be going to in to bat for openAPI + FHIR for further details about healthcare for healthcare apps
Øyvind Aassve (Aug 13 2018 at 12:35):
Thanks Grahame, with regards to the batting openAPI+FHIR for apps, are you thinking openAPI might have a role for web access/ security?
Grahame Grieve (Aug 13 2018 at 12:42):
well, we aren't going to put that stuff in our resources, that's for sure.
Øyvind Aassve (Aug 13 2018 at 14:09):
OK, good, Ill take this with me in the discussions with them. Cheers
Mario Hyland (Sep 17 2018 at 16:34):
@Grahame Grieve regarding OpenAPI - there is a conference next week in Nashville, TN - OpenAPI Initiative, the API Strategy & Practice Conference https://events.linuxfoundation.org/events/apistrat-2018/ @Mark Scrimshire will be attending. Perhaps he would act as an envoy for you - regarding this discussion. US Digital Service is heavily backing OpenAPI - and I have been involved in a few discussions about the VA, DoD and OpenAPI interfaces. FHIR was being identified as being "noncoforming" at this time. We would direct any future reference to the FHIR IG's as how FHIR will address this; but we are unable to point to a current IG which is conformant to OpenAPI at this time. I think we should work on a reference example which meets OpenAPI requirements (even if its just a reference example). Expect in the coming months more of these types of conversations to be occurring. Might be worthy of a blog (when we have an example ready).
Mark Scrimshire (Sep 17 2018 at 16:51):
@Grahame Grieve @Mario Hyland I would be happy to relay any messages at the event. On the CMS Blue Button project we have been thinking about how we can integrate with the Swagger/OpenAPI spec to document our API. I had in fact taken a first attempt at using a node package to document the fhir api and then filtered down to the resources and actions we were supporting: https://github.com/CMSgov/bluebutton-web-server/blob/master/apidocs/bbonfhir_swagger.yaml
Mario Hyland (Sep 17 2018 at 17:19):
@Mark Scrimshire I think the FHIR community was looking at the IG Publisher to support this need, meaning - if the FHIR Tooling does its job, you would receive credit or publish a machine readable and OpenAPI compliant artifact. An idea would be to point folks like the US Digital Service to the HL7 event at the end of Sept in Baltimore as a place to continue these conversations. It would be great if we could get a few folks from the OpenAPI community to engage with the FHIR Community conversation.
Mark Scrimshire (Sep 17 2018 at 17:23):
@Mario Hyland Yes - It would be great if the IG Publisher produced the OpenAPI documentation.
Adam Flinton (Sep 17 2018 at 18:31):
I would love to see an openapi <> fhir tool. Would make doing stubs (both client & server) much easier. Could even use it with aws api gateway etc.
Grahame Grieve (Sep 17 2018 at 23:40):
so @Mark Scrimshire at the conference, our major issue is inconsistency around json schema. I think that the json schema currently produced for the build is correct, but quite a few tools dsisagree
Grahame Grieve (Sep 17 2018 at 23:40):
the openAPI part should be good to go I'll find an IG that actually exposes this
Grahame Grieve (Sep 18 2018 at 00:04):
https://build.fhir.org/ig/HL7/US-Core/server.openapi.json
Grahame Grieve (Sep 18 2018 at 00:04):
and https://build.fhir.org/ig/HL7/US-Core/client.openapi.json
Michele Mottini (Sep 18 2018 at 13:12):
I did have clients asking for Swagger descriptions of our FHIR API, and I always failed at the JSON schema part - meaning I could not find a way to generate correct JSON schemas for the responses
Mario Hyland (Sep 18 2018 at 17:21):
@Grahame Grieve apologies for jumping ahead slightly here, but have you given any thought to our process for operationalizing this? We have the CapabilityStatement for FHIR - but in its current native format it does not seem to answer the mail for (US Digital Services) the OpenAPI requirements - do we propose exposing in addition to metadata another URL specifically for OpenAPI support? Or, from your perspective should the FHIR CapabilityStatement in FHIR native JSON format meet the OpenAPI requirements as-is? And, is this our ask or end goal objective (for @Mark Scrimshire )?
Yunwei Wang (Sep 18 2018 at 17:23):
@Grahame Grieve in the server.openapi.json, should there a # sign in the ref?
$ref": "http://build.fhir.org/fhir.json.schema#/definitions/OperationOutcome"
Grahame Grieve (Sep 18 2018 at 20:02):
yes I think there should be.
Mark Scrimshire (Sep 25 2018 at 13:50):
@Grahame Grieve apologies for jumping ahead slightly here, but have you given any thought to our process for operationalizing this? We have the CapabilityStatement for FHIR - but in its current native format it does not seem to answer the mail for (US Digital Services) the OpenAPI requirements - do we propose exposing in addition to metadata another URL specifically for OpenAPI support? Or, from your perspective should the FHIR CapabilityStatement in FHIR native JSON format meet the OpenAPI requirements as-is? And, is this our ask or end goal objective (for @Mark Scrimshire )?
I am at #APIStrat and have been talking with Kin Lane. He is working with the VA on their OpenAPI work. I suggested that he come to the next Connectathon (San Antonio in 2019?) and present that work. In the meantime we can see how we can draw kin into these OpenAPI conversations.
Grahame Grieve (Sep 26 2018 at 05:16):
well, I think that question is wrong way around. If I was coming from the openAPI communicty, how would I expect to find the openAPI statement?
Grahame Grieve (Jun 02 2019 at 07:36):
There's a bunch of openAPI validators out there - can anyone comment on how good they are, and whether there's on that I should put my faith in when I work on swagger generation this week?
Grahame Grieve (Jun 02 2019 at 07:37):
(@Michael Hansen)
Josh Mandel (Jun 02 2019 at 13:34):
Do you mean tools that check a set of OpenAPI definitions and ensure they're valid, or tools that look at instance data and validate them against OpenAPI definitions?
Michael Hansen (Jun 02 2019 at 16:19):
@Grahame Grieve , what I have struggled with is that there are OpenAPI/Swagger definitions that are technically valid (according to various tools), but other tools that consume the "valid" openapi specs fall over (usually because of too deeply nested schema definitions). So my recommendation would be use whatever validator makes sense in your tool chain and validate that you can generate a client based on the spec using something like AutoRest (https://github.com/Azure/AutoRest).
Grahame Grieve (Jun 03 2019 at 07:43):
I mean, how do I validate that i'm producing valid openAPI documents
Grahame Grieve (Jun 03 2019 at 07:43):
clearly, all openapi tools require a long tool chain based around npm. I'll have to invest in figuring that out
Shovan Roy (Jun 03 2019 at 22:36):
@Grahame Grieve , did you try https://swagger.io/tools/swagger-editor/download/ and the online editor https://editor.swagger.io/ it's still npm based though
Brian Postlethwaite (Jun 03 2019 at 23:40):
That one struggles with the scale of it.
Grahame Grieve (Jun 04 2019 at 02:58):
ok. so here's an updated schema that I think is mostly correct (thanks @Brian Postlethwaite ). we definitely have issues with schema, but I can't get going
Grahame Grieve (Jun 04 2019 at 02:58):
Grahame Grieve (Jun 04 2019 at 02:59):
the editor at https://editor.swagger.io/ says
Resolver error at paths./metadata.get.responses.200.content.application/fhir+json.schema.$ref Could not resolve reference: Failed to fetch
the reference it can't resolve is:
http://hl7.org/fhir/STU3/fhir.schema.json#/definitions/Bundle
Grahame Grieve (Jun 04 2019 at 02:59):
that looks like it should resolve to me...
Brian Postlethwaite (Jun 04 2019 at 03:00):
The first block for it is that the editor is over https, so it can't access an insecure http site - developer console should state that,
but when you change that to https, the size/complexity gets you.
Brian Postlethwaite (Jun 04 2019 at 03:02):
This request has been blocked; the content must be served over HTTPS
Is the message that you would be seeing in the browser developer console.
Grahame Grieve (Jun 04 2019 at 03:02):
that's... .bad
Grahame Grieve (Jun 04 2019 at 03:05):
so the http/https thing is truly problematic.
Grahame Grieve (Jun 04 2019 at 03:05):
but yes, after that it crashes the editor
Grahame Grieve (Jun 04 2019 at 03:06):
hah I can no longer use the editor at all. awesome.
Brian Postlethwaite (Jun 04 2019 at 03:06):
Yup, for me takes 45seconds to download the 1.5MB, then memory crash.
Grahame Grieve (Jun 04 2019 at 03:07):
and the editor remembers state... so bang
Brian Postlethwaite (Jun 04 2019 at 03:08):
Yeah, that's the really sucky part. Disconnect network so that it can't get at that address?
Brian Postlethwaite (Jun 04 2019 at 03:16):
The developer tools helped me crack around that long enough to change the URL back to http
and therefore not work...
Vadim Peretokin (Jun 04 2019 at 07:57):
The demand for OpenAPI when the quality of the tooling is like this puzzles me
Josh Mandel (Jun 04 2019 at 12:42):
It forces you to do simple stuff -- which is usually good :-)
Josh Mandel (Jun 04 2019 at 12:43):
Also a lot of people use it like a documentation generator -- so even if things like code generation and data validation don't really work, you still get a pretty enough documentation page
Brian Postlethwaite (Jun 04 2019 at 12:48):
Which is funny when fhir tooling has so much more in both respects.
In my case the API management tools my company uses wants one.
nicola (RIO/SS) (Jun 04 2019 at 14:52):
We were able to run swagger-ui with simplified schema in one file with some lags. Guys just do not expect such amount of generated metadata - it's a good case for swagger developers to tune their tools. I think we should report this issues.
Shovan Roy (Jun 04 2019 at 22:26):
I'm using a work around in my OpenAPI spec. pulling the profile reference form the CapabilityStatement and using it as 'externalDocs' in the schema definition.
Grahame Grieve (Jun 05 2019 at 10:00):
what problems does that save?
Brian Postlethwaite (Jun 05 2019 at 10:52):
This would then prevent the tool from trying to load in the schema...
Brian Postlethwaite (Jun 05 2019 at 10:53):
But does provide access to the documentation via the links. :smile:
René Spronk (Nov 27 2019 at 03:19):
I'm not a swagger expert by any means - one of my trainees in a FHIR training course in Brussels asks: so what's the latest status in terms of using Swagger UI for the FHIR API ? Can it be made to work, would you recommend the approach ?
Grahame Grieve (Nov 27 2019 at 04:54):
the API part is fine, and the IG publisher generates openAPI documents for capability statements (and you can give it a swagger template to fill out and so doing specify your security details etc). But the schema part is a mess, and I don't think that's functional at this time.
Niharika (Nov 27 2019 at 07:34):
I'm not a swagger expert by any means - one of my trainees in a FHIR training course in Brussels asks: so what's the latest status in terms of using Swagger UI for the FHIR API ? Can it be made to work, would you recommend the approach ?
Yes, ofcourse. Swagger can be used to implement FHIR spec and hit the endpoint.
Jose Costa Teixeira (Jan 07 2020 at 08:51):
Isn't the schema necessary for write operations? I tried removing it to get rid of the errors, but with this I lost the ability to post from swagger UI
Jose Costa Teixeira (Jan 07 2020 at 10:56):
And how do I get POST to work? my CapStatement looks like this, but my swagger json does not contain POST.
pasted image
Jose Costa Teixeira (Jan 07 2020 at 10:57):
I'm sure I'm doing something wrong, or at least not doing something right..
Grahame Grieve (Jan 13 2020 at 06:52):
wooah I had put/post the wrong way round on create/update. Try again after the next release
Jose Costa Teixeira (Jan 14 2020 at 18:48):
OK, POST is there.
Jose Costa Teixeira (Jan 14 2020 at 18:48):
SwaggerUI doesn't work , even if i copy the schemas to my local machine to avoid CORS.
I guess this is because of schemas. From initial research, it seems I may need to de-reference and convert the schemas...
Is there any working example of OpenAPI POST from a CapStatement?
Grahame Grieve (Jan 14 2020 at 19:08):
json schemas... an openAPI varies from them...
Grahame Grieve (Jan 14 2020 at 19:08):
json schemas... an openAPI varies from them...
Jose Costa Teixeira (Jan 14 2020 at 19:11):
Ok i read some things about converting standard json schemas to openAPI,
https://www.npmjs.com/package/json-schema-to-openapi-schema
Jose Costa Teixeira (Jan 14 2020 at 19:11):
I will see if this leads to somewhere.
Jose Costa Teixeira (Jan 14 2020 at 19:13):
Perhaps we just have to see when(ever) openAPI / swagger tools adopt json schema.
Brian Postlethwaite (Jan 15 2020 at 10:07):
I've had a quick look at doing some of it, and did some post processing to reduce complexity, made it load for my limited case, but that's about it.
Brian Postlethwaite (Jan 15 2020 at 10:08):
Key was to remove the extensibility where its not used. (from profiles)
Brian Postlethwaite (Jan 15 2020 at 10:09):
Not 100% but at least loaded for display.
Brian Postlethwaite (Jan 15 2020 at 10:09):
And we know that it doesn't really work anyway for truely complex objects.
Jose Costa Teixeira (Jan 25 2020 at 21:01):
@Brian Postlethwaite do you have something somwehere?
Jose Costa Teixeira (Jan 25 2020 at 21:03):
I did some test with some conversion libs but did not work. some circular reference or so
Jose Costa Teixeira (Jan 25 2020 at 21:07):
While openApi does not fix their stuff or we cannot figure out a conversion, would it be an option to remove the fhir schemas and just point it to an object?
Jose Costa Teixeira (Jan 25 2020 at 21:09):
something like this
json
"200": {
"description": "the capbility statement",
"content": {
"application/fhir+json": {
"schema": {
"$ref": "#/definitions/objBody"
}
}
...
,
"definitions": {
"objBody": {
"type": "object"
}
}
}
Jose Costa Teixeira (Feb 04 2020 at 23:53):
I'm interested in publishing openAPI via SwaggerUI.
(I think) I got this working by manually removing the schema information. This made it work, although it does not present a schema in the Swagger UI.
Jose Costa Teixeira (Feb 04 2020 at 23:55):
Before suggesting this as an option, and ask Grahame to consider ignoring schemas when generating openApi json (possibly depending on a variable), what do others think? Any opinions out there?
Ward Weistra (Feb 05 2020 at 04:37):
I've previously generated a Swagger file from a FHIR server metadata statement with this npm package: https://www.npmjs.com/package/fhir-swagger (https://github.com/rbren/fhir-swagger).
Generated the swagger.json file with this command: fhir-swagger --fhir_url "https://vonk.fire.ly" --conformance_path="/metadata" --dstu3 --output swagger.json. Can be rendered (with sufficient patience) in https://editor.swagger.io.
shachar zilbershlag (Feb 05 2020 at 10:20):
(deleted)
Last updated: Apr 12 2022 at 19:14 UTC
