Getting Started

[virkt25]

For http://v4.loopback.io/getting-started-oasgraph.html some things should be changed.

As per a user comment (loopbackio/loopback-next#1762), for git clone it's more preferable to use the https link instead of the ssh link.

That would be a short term thing. As per strongloop/v4.loopback.io#43 the Developer Experience of having to link a dependency is very poor. It's much more preferable to have the following:

npm i -g oasgraph
oasgraph ./openapi.json

and for production a user can install the dependency via package.json and build out a npm script as follows:

start: ./node_modules/oasgraph ./openapi.json

And then be able to run npm start

---

Lastly the getting started page is very all over the place and not a good guide to "get started" as it currently stands as it assumes a user has an app already.

A much better Getting Started would be to say that lets build on LoopBack's Getting Started ... or add a step to clone a project from LoopBack 4 as follows:

npm i -g @loopback/cli
lb4 example todo
cd example todo // You can even point to LB Documentation for this but it's better if it's all on 1 page. 
npm i oasgraph // After this is available via npm
npm start
// Visit /openapi.json and save to disk at './openapi.json' --> Maybe we can provide a script to pull it from server and save to disk?
Ctrl+C
// Add a command to package.json as follows:
> start:oasgraph: "./node_modules/oasgraph ./openapi.json"
npm run start:oasgraph
// Visit GraphQL Link

[ErikWittern]

@virkt25 Thanks for the feedback.

Switching to a model where OASGraph is installed globally is not necessarily a good option for us, because it requires to integrate the CLI capabilities with the library capabilities. OASGraph is intended to be a library primarily that produces GraphQL schemas that can be used with any application server (e.g., Express, Hapi, LoopBack etc.). The CLI happens to use Express to quickly set up a server for demonstration purposes. By integrating the CLI capabilities with the library capabilities, we would have to make express and express-graphql "normal" dependencies (they are currently devDependencies), which I really do not want to do.

I currently see three options:

1. We stick with npm link. Pros: express and express-graphql stay devDependencies, OASGraph remains a library primarily. Cons: developers have to run npm link, with all its issues (like dealing with a lack of permissions).
2. We combine cli.js and index.js (current state, as @Alan-Cha implemented the proposed changes). Pros: developers can install OASGraph globally to avoid having to run npm link, and we would focus on the CLI capabilities. Cons: we add two significant dependencies.
3. We decouple oasgraph from a newly created oasgraph-cli (proposed by @dhmlau ). Pros: clean separation of concerns. Cons: 2 repos may cause confusion and increase maintenance efforts (i.e., always having to update oasgraph-cli whenever we update oasgraph).

Given that the focus of OASGraph is to be a library, and the CLI is merely intended to exemplify how to use the library, I am in favor of option 1.

[marioestradarosa]

OASGraph is intended to be a library primarily that produces GraphQL schemas that can be used with any application server

@ErikWittern , I haven't installed but I will play around with it this weekend. However, please my apologize if this question is out of sync. If this is a library, can it be installed inside loopback 4 as a dependency and link the GraphQL interface to the internal loopback 4 artifacts ?, such as the controllers or repositories or any new kind of loopback4 artifact that can implement the interface?.

[ErikWittern]

@marioestradarosa Good question! As of now, there is no integration between loopback 4 and OASGraph on an individual artifact level. There is a clear synergy between loopback and OASGraph as loopback is based around the OpenAPI Specification, which is the input for OASGraph. We have yet to look into a deeper integration of the two.

We plan to shortly publish an additional article on how to use OASGraph as a library (in contrast to the CLI usage currently described in the getting started guide).

[marioestradarosa]

👍 thank you for your prompt reply. I guess for loopback 4 for now, the next step would be to install OASGraph as a dependency and generate in an end-point the GraphQL schema(s) automatically ~~~and in the future allow GraphQL clients to contact the loopback 4 app that seamlessly produce the data requested, does it make sense?.~~~ This way OASGRAPH focus on the transcoding task only.

[marioestradarosa]

I didn't have any experience with GraphQL before, so I did some home work this weekend and finally understood 😄 the benefits and the potential for OASGraph library.

Here is a small video presentation summarizing my findings and the way to integrate this amazing library with LoopBack 4.

Note that the current OASGraph CLI is only used to test an openapi.json spec file, this won't work in production, probably the best way is to use the mechanism I placed on the video, this way, I didn't have to install the OASGraph CLI or run npm link etc.

https://www.youtube.com/watch?v=s2hScucNmaA

[Alan-Cha]

Wow, incredible video, Mario! Really great work! Very well made!

@ErikWittern and I are working on tutorials for OASGraph. I think this video could easily be turned into another one, focusing on integrating OASGraph into a LoopBack app, which so far we have avoided for lack of understanding of LoopBack. Would you be interested in working on a new tutorial with us?

You should also keep an eye out for the next few tutorials if you are interested in using OASGraph more. The next two will highlight link objects, which are small additions to the OAS that will greatly increase the power of the GraphQL interface.

[Alan-Cha]

After reviewing the video a few more times, we found a few typos.

• In the title slide, it says "OASgraph" instead of "OASGraph".
• There is a typo in the code where it states srict: false instead of strict: false

Sorry for nitpicking! Just wanted to help out so don't take it the wrong way. The video will be an incredible resource for anyone who wants to learn about OASGraph.

[marioestradarosa]

@Alan-Cha , thanks for your comments. Yes, indeed the video can be considered a draft to summarize my findings this weekend and I would be more than happy to help you with the tutorials.

As for loopback 4 , this is an unofficial way to integrate it with OASGraph library, following your current documentation and examples. The Success of the project is to allow the application developer discover the architecture, integration and benefits of your amazing work.

[Alan-Cha]

Concerning the CLI usage, I agree with Erik, that we should stick with npm link. Fully supporting the CLI tool will mean we have to move express and express-graphql into dependencies and I think that strays too far from the intended usage. Moving the CLI to a separate repo on the other hand will be confusing to our users.

We plan on reverting these changes (currently the CLI tool can be found in the main library files) soon.

[Alan-Cha]

@marioestradarosa I think there is some talk of integrating OASGraph into the LoopBack CLI tool so that a user start a GraphQL server without touching any code. I think we should look into that as well! 😄

[marioestradarosa]

@Alan-Cha , in IMHO, if OASGraph was built to be used by other frameworks, you can continue as follows:

1. Improve OASGraph CLI to increase developer experience. For instance you can receive the OAS content from a url aside from the local file as for now. This allows developers to test it without touching their current application, but to my understanding this might be just to test it for now.

2. Give examples on how to Integrate the OASGraph library depending upon the framework.

In the case of a specific framework such as loopback 4 , the team can work on some integrations as follows:

1. Using LB4 CLI to act as the OASGraph CLI but will get the OAS file from the current application, something like lb4 start-graphql --port 3001
2. Using LB4 CLI to add some code to an already existing loopback 4 application, such as lb4 --enable-graphql inside the application and it will modify the code to something similar showed in the video
3. Using LB4 CLI when generating an application with an option such as lb4 myapp --with-graphql will create internally the necessary code to start automatically the graphql server. This option could have in the application.ts something like { options: {graphql: enable: true, port: 30001 }} more or less 😄

So in summary, the OASGraph should stay independent to work as a library, enhance its CLI tool to improve the developer experience, and Loopback 4 has endless posibilites to use it to make it more powerful than it is at this moment.

[ErikWittern]

@virkt25 @marioestradarosa We tried to improve the getting started experience with the above-stated pull request. This repository's readme now features a new Getting Started section, that points to three resources (so far): the getting started guide for using OASGraph as a CLI, a newly added tutorial for using OASGraph as a library, and a newly added tutorial for using OASGraph in combination with LoopBack 4.

@marioestradarosa Your video is really nice. Would you be ok if we link to it from the newly created Getting Started section?

[marioestradarosa]

Would you be ok if we link to it from the newly created Getting Started section?

Yes, Please, it is an honor. As I told Alan, I did it quickly during weekend, sorry for typos that he found etc. 😄 . I will be working on subsequent videos with loopback4 integration more carefully.

[ErikWittern]

@marioestradarosa Fantastic, thank you! We will create a link in one of our next pull requests.

I also like your proposal of extending the CLI capabilities by allowing to point to URLs. I created a dedicated issue #40 to cover this case.

[bajtos]

@ErikWittern I would strongly like us to reconsider the decision around the way how the library vs. the CLI is structured and what is the user experience for consumers of oasgraph.

First of all, bundling the CLI tool with the library is almost always a bad thing. We have been bitten by this several times by now, for example in loopback-sdk-angular and strong-globalize. By having the CLI tool in the same package as the library, we are forcing library users to install extra dependencies for the CLI part, which are usually not needed by library users. Another consequence is a bigger surface for potential security vulnerabilities, as applications running in production are depending on unused CLI-related libraries.

At the same time, shipping an npm module that works only with express and express-graphql (presumably only with a specific semver-major versions of those modules) and not listing these modules in the dependencies, is sort of an anti-pattern in Node.js world. At minimum, you should clearly spell out the required modules in peerDependencies.

Personally, I would really like to see two npm packages:

• oasgraph - the library runtime
• oasgraph-cli - a CLI tool

Please note that you don't necessarily have to create another GitHub project for the CLI tool. By now, the concept of a monorepo hosting multiple npm packages is pretty much well explored and there is plenty of tooling to support it, from lerna (which we use in LoopBack), through pnpm to yarn workspaces.

[ErikWittern]

@bajtos Thank you for the input! Making the core and the cli parts separate npm packages already one of the options we considered before #30 (comment), but I think that discussion was not yet decided.

I already saw arguments for splitting OASGraph core and cli up, but I am furthermore convinced by your arguments regarding implications for security (in production) and eased management by tools like lerna. But primarily, the issues with the dependencies being unclean would get resolved by this proposal.

I will file a dedicated issue.