Swagger for API documentation

[twils...@gmail.com]

Has anyone tried to use Swagger (http://swagger.io/) to generate API documentation and client tools for HAPI FHIR? I'm looking into it and trying to figure out where to start.

[Николай Рыжиков]

In dev skype chat were some discussions, but without practical application yet.

[James Agnew]

Yup- the idea of using something like Swagger has been discussed a few times but so far it hasn't gone anywhere.

Personally I *really* like swagger but I kind of wonder whether it makes sense for fhir, for a couple of reasons:

1. FHIR defines its own way for servers to declare what they support in terms of operations and data model (the server's conformance statement and profiles)

2. Swagger's auto generated documentation and clients are useful for APIs that have nothing else, but FHIR has tons of documentation and lots of great purpose-built clients available

3. In my experience at least, Swagger's tooling gets overwhelmed and sluggish pretty quickly if you use it on APIs with particularly large/complex data models, and FHIR's is definitely large.

James

--
You received this message because you are subscribed to the Google Groups "HAPI FHIR" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hapi-fhir+...@googlegroups.com.
To post to this group, send email to hapi...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/hapi-fhir/e3357391-d495-4b8f-bb43-3b0037efd81c%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Rob Resendez]

I'm trying to find the code responsible for discarding certain properties from resource models whenever using fhirContext.newJsonParser().encode...

In order to get swagger to report a model that matches the FHIR spec, custom "swagger.ModelConverters" must be implemented. This looks like quite a tedious undertaking and I'd like to implement something generic that does it in the same way that the IParser implementations do it... but I'm having a hard time finding the relevant Hapi code.

I'd like to get this working using swagger-core directly, but for others who may be looking at swagger...  I have found (but not tried) this project that produces swagger.json using a fhir conformance statement:  https://github.com/bobby-brennan/fhir-swagger

[James Agnew]

Hi Rob,

What do you mean "discarding"? Like are you wondering where the code is that causes the parser to ignore elements it doesn't understand?

If you want an in-memory metamodel you could use to generate swagger's model definitions, one thing you could do it use HAPI's resource defintions and their accompanying child definitions..

The following would give you the patient def:

ResourceDefinition def = ctx.getResourceDefinition("Patient"); 

Calling methods like getChild() on that lets you walk the hierarchy. You'd need to spend a bit of time with a debugger though seeing what gets returned, since that part of the API isn't as well documented as the more "user facing" stuff.

Cheers,

James

To unsubscribe from this group and stop receiving emails from it, send an email to hapi-fhir+unsubscribe@googlegroups.com.

To post to this group, send email to hapi...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hapi-fhir/df6ba3a7-e963-4e0e-9e99-ca374624091f%40googlegroups.com.

[Rob Resendez]

> ... where the code is that causes the parser to ignore elements it doesn't understand?

This is exactly what I was looking for. eg... if I you Gson directly to serialize a "Patient" object, you get a bunch of noise... if you use the hapi parser, you get a perfect match to the fhir spec.

I have just looked, briefly, at fhirContext.getResourceDefinition()... that's pretty neat! At this point I'm trying to research what might be the path of least resistence in terms of producing a swagger.ModelConverter. My prior train of thought was to use some reflection or logic similar to the hapi parser impl to create an adapter; but, this resource definition meta data seems very well suited to that end.

I'd wager you use these to assist in building the conformance statement?  At this point, for lazy programmers such as me, using that 3rd party tool that converts a conformance statement to a swagger definition has some appeal... as you pointed out previously in this thread:

FHIR defines its own way for servers to declare what they support in terms of operations and data model (the server's conformance statement and profiles)

[James Agnew]

Gotcha.

Yeah, I'd say using the resource definition stuff would probably be the path of least resistence to getting a Swagger modelconverter up and running. Happy to offer any help I can in getting that working, it certainly sounds like something others would find useful.

Cheers,

James

To unsubscribe from this group and stop receiving emails from it, send an email to hapi-fhir+unsubscribe@googlegroups.com.

To post to this group, send email to hapi...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/hapi-fhir/c5a436d8-26ba-492d-a8f4-7ba7f557f1f6%40googlegroups.com.

[m.wede.s...@googlemail.com]

Hi Rob,

are you working on something to generate HAPI code from a swagger yaml/json file? Or are you trying to build a swagger file from a FHIR conformance statement?

I am working on a commercial project that builds new FHIR services, both the server and the client side. For that I am currently evaluating if we could generate code from a FHIR conformance statement. The beauty of that would be to have the conf statement as a contract between e.g. server and client parts and be able to implement both independently. Further we would love to generate as much code as possible from the conf statement. That would save us a lot of manual work and eliminate a big source of error.

So I am pretty interested in what you may be doing :) In case you are working on generating HAPI code: are you planning to make your work freely available, on github maybe?

Cheers

Marco

[Rob Resendez]

Marco -

My goal was just to generate a swagger.json definition - not code

[m.wede.s...@googlemail.com]

Hi Rob,

Thanks for your reply. Did you give Bobby Brennans fhir-swagger a try then? I only tested it quickly, but it works as it should, I would say. So maybe that saves you some effort.

Cheers

Marco

[m.wede.s...@googlemail.com]

Hi Rob,

did you make progress in your effort to generate a swagger.json from HAPI code?

Cheers

Marco

Am Montag, 13. März 2017 20:47:18 UTC+1 schrieb Rob Resendez:

[Malcolm McRoberts]

Swagger is also needed for some of the API management tools.