Stream: IG creation
Topic: SwaggerUI
Jose Costa Teixeira (Jan 25 2021 at 05:54):
Has anyone used the generated OpenAPI files in SwaggerUI?
Grahame Grieve (Feb 01 2021 at 20:58):
@Gino Canessa ?
Gino Canessa (Feb 01 2021 at 21:00):
I have generated core spec files and used them in SwaggerUI (e.g., 4.0.1). I have not gotten to loading profiles into the code generator yet though.
Jose Costa Teixeira (Feb 01 2021 at 21:05):
I want to see the feasibility of adding a SwaggerUI page in an IG. Anything I should look at?
Gino Canessa (Feb 01 2021 at 21:19):
opens can of worms =). The biggest issue is that there is a lot of variation based on what tooling people are using. Issues such as:
- variable casing (some tools I've tested against want the first character lower-case, others want upper-case)
- support for circular definitions
- support for referential definitions
- requiring comments vs. prohibiting them
- etc.
It was painful enough trying to come up with a single definition that works for a people that I gave up on the output files. Instead, I've tried to make progress on tooling so that people can generate what they need.
Is that the kind of info you are looking for?
Jose Costa Teixeira (Feb 01 2021 at 21:31):
I'm one step behind, I guess.
Doesn't the publisher already handle the generation of the json schema? How far are we from the idea of throwing that json at swaggerUI or something like this
https://github.com/Redocly/redoc
?
Gino Canessa (Feb 01 2021 at 21:49):
Yes it does. Generating a definition that matches those properties is certainly possible.
Unfortunately, if you try to run those definitions through various toolchains many will reject them. In the two first use cases I was asked to look at, the toolchain requirements meant that a single set could not pass both sets of checks. One toolchain required all models start with a lower-case letter, while the other required they start with an upper-case letter (as one issue). There is no rule about it in OpenAPI, and we can certainly set a convention in FHIR (e.g., what the publisher exports), but the file isn't usable if it won't pass validation in someone's workflow. It would be great if we had the leverage to say "this is the way we do it, so adapt the toolchain", but I don't think we're quite there yet.
My question becomes: why are you generating them? If the goal is to give people another way to visualize the models, no problem. If the goal is to allow people to use the definitions with existing systems, :shrug:
There are similar challenges with just exporting code from OpenAPI. Since most people don't use raw models, you need to try and align the exported code with various SDKs (e.g., test exporting Java code and then integrate with the hapi libs, same for C# and Firely, etc.). I'm not as familiar with the Java libraries, but I can say in the C# side that even if we matched conventions, the generated code would not work. The libraries do a lot of work to make things 'nicer' for developers, so the raw models aren't typically exactly exposed.
It may be interesting to build export modules that are compatible with the various libraries... in fact, it sounds like so much fun that I've added it to my list. But my list is pretty long right now, so it will be a while before I can get there.
Gino Canessa (Feb 01 2021 at 21:58):
Rereading my above comments, it sounds pretty negative. It shouldn't be, but I'm not sure how to fix it. I don't want to discourage work and exploration in the area, but I also want to communicate the challenges.
I would argue that exporting some definition is better than none. I just want you to know that you are going to get a lot of feedback when people start trying to use them about changes they want.
Ward Weistra (Feb 04 2021 at 11:16):
Nice topic! I would love to provide an OpenAPI/Swagger view on any Simplifier.net project or package. (Created OpenAPI docs for the Package API while exploring)
I've tested https://www.npmjs.com/package/fhir-swagger as a command line tool to create a swagger.json file from a server conformance statement (/metadata), which worked well, but it seems limited to showing the supported profiles.
A full conformance statement, which not many projects/packages have, is likely necessary to even know what the user intended the spec for; whether it's a server or an app, whether it wants to receive/send data conform certain profiles.
I think we'll start with an OpenAPI-ish view of per package/project:
- the different used base resources as endpoints with the possible GET/POST/PUT/DELETE formats
- under that the different profiles, search parameters, operation definitions
- and under that linked examples as example data
Would that cover what you want to see in your OpenAPI view?
Ward Weistra (Feb 10 2021 at 13:19):
@Jose Costa Teixeira @Gino Canessa if you missed it :point_up:
Gino Canessa (Feb 10 2021 at 16:05):
Hi Ward, that sounds like a great starting point.
Where I am stuck is in how the files are going to be used. If the idea is to generate documentation / views, this is fantastic. However, if these are going to be used for code generation* or deployment pipelines, there are a lot of things that need to be configurable at runtime. To pick a different example from earlier: what MIME types are going to be included on the endpoints? If you are using these files to configure routing / security rules, the MIME types have to be defined and match what the server supports. An even simpler use case is for a read-only set of definitions.
So far, I've been going down the road of putting this in the generation. Maybe it's better for us to pick a standard model and then transform the specs as necessary after? Or some other process?
*as mentioned here (and on another thread recently, but I don't have a link handy), code generation is its own problem - it's unlikely that anyone actually wants raw objects, as they would probably prefer code that interoperates with their FHIR library. Since the conventions aren't the same across languages, this will have to be built out per language as well.
Jose Costa Teixeira (Feb 10 2021 at 16:09):
I think my goal was relatively modest, compared to what is described:
I want to add a SwaggerUI or ReDoc frontend in an ImplementationGuide.
In there, we could add a url pointing to a server that is known to support this and say "here's a test server where you can test these GETs and POSTs)
Ward Weistra (Feb 11 2021 at 14:04):
@Jose Costa Teixeira Good one to add, configure a test server and try it out live.
@Gino Canessa This thread? https://chat.fhir.org/#narrow/stream/179166-implementers/topic/XSD.20Schemas.20from.20FHIR.20Profiles.20for.20Code.20Generation
Indeed, I was only thinking about documentation here. And indeed, already there there's a lot to be configured to come from a set of resources or even a capability statement to a full API description.
And we also had some requests for downloading classes from resources on Simplifier.net. With your code we might be able to offer that at least for .NET, but we're still gathering user requirements on what they'd expect to be in there.
Gino Canessa (Feb 11 2021 at 16:10):
I love ReDoc! =)
I am curious to see how more advanced cases work with the generic (non-FHIR) serializers and parsers. Generally they seemed to behave in my testing, but I haven't checked to see if everything is valid, just if it "worked".
I'm not as familiar with IG packages from Simplifier (unless they are the same as the ones generated by the IG build). Does it have enough information that you don't need a a server/capability statement (or the core spec definitions) to generate the definitions? For example, if someone is profiling the Patient resource, in addition to what is locally defined I think you need:
- search parameter definitions for the resource (so you can successfully do a
GET) - structure for
Bundle(so you can search - may not be needed on every profile) - structure for
OperationOutcome(which the IG schema seem do via external reference - not sure if this works)
...
For the C# code, yes - I'd like to explore that. It is a bit down my list right now though, so if anyone else wants to explore I'd love to see the outcome =)
Ward Weistra (Feb 12 2021 at 09:09):
@Gino Canessa A package is not much more than a snapshot of a FHIR project in time, there's no requirements from Simplifier.net on what resources are minimally contained. So, it may well only contain a Patient profile. That's indeed why I'm really looking very generic solutions :smile:
Last updated: Apr 12 2022 at 19:14 UTC
