Project Context

The client is working on one API. To build out this API, its needed capabilities have already been defined, and they have even created a Swagger document to use. But when attempting to implement this Swagger document in the API, they have run into several issues.

We will analyze why the issues occur and find a solution to fix them.

Challenge Context

In this challenge, we will

• Analyze different available tools, such as swagger-ui-dist and check why they do not work well with provided openapi file

• Ideate and setup a new method to implement mocks from a swagger document that has multiple $ref tags to various definitions

• Create document to explain what you find and how to solve the issues

• Create POC to prove your idea

Challenge Details

Individual Requirements

Here are the list of issues the client provided:

• The document uses $ref tags which reference documents via a URL. When using swagger-ui-express or swagger-ui-dist, it has a hard time working with these tags.

• When pulling the referenced document down, we may be able to set up a local reference from within Swagger, but we lose the dynamic capabilities associated with that document.

• When pulling the referenced document down and attempting to incorporate it as part of one single document in Swagger, we run into an issue with the Swagger page taking too long to attempt to load it.

• While experimenting some of the libraries available to start up a mock service, this error is encountered

Besides the above issues, we also need to remove all PUTS/POSTS from the swagger documentation as it should be readonly GETS in mock api.

The OpenAPI file we are going to use in this challenge:

https://build.fhir.org/ig/HL7/US-Core-R4/us-core-server.openapi.json

NOTE:

• The solution will use Node/TypeScript.

• Single Swagger page should display with the API. It can be the result of multiple Swagger files.

• The solution could be either to build on top of existing tools, such as swagger-ui-dist, or  to provide some scripts to preprocess the OpenAPI file.

Final Submission Guidelines

Document of your idea

PoC codebase