Rejigged README a little #142
Conversation
I'm excited about API Flow, but the README had me installing from source with me only noticing I could just yarn install later. I think the default for most folks is installing the package, not building from source.
I've also added `const path = require('path');` as it was erring before that.
Still, this is giving me trouble:
```
$ node scripts/openapi_to_postman.js
/Users/psturgeon/src/apis/scripts/openapi_to_postman.js:15
const promise = ApiFlow.transform({
^
TypeError: ApiFlow.transform is not a function
at Object.<anonymous> (/Users/psturgeon/src/apis/scripts/openapi_to_postman.js:15:25)
at Module._compile (module.js:569:30)
at Object.Module._extensions..js (module.js:580:10)
at Module.load (module.js:503:32)
at tryModuleLoad (module.js:466:12)
at Function.Module._load (module.js:458:3)
at Function.Module.runMain (module.js:605:10)
at startup (bootstrap_node.js:158:16)
at bootstrap_node.js:575:3
```
I'd love to get the README in line with how things work, just gimme some hints! :)
| make runners TARGET="node web webworker" | ||
| ``` | ||
|
|
||
| ### Paw |
There was a problem hiding this comment.
It doesn't really explain how this is Paw related, kinda seems like this is for building outputs in general. Remember, a lot of people will have no idea that this repo has anything to do with paw. It's just an A <> B converter.
| ```sh | ||
| git clone https://github.com/luckymarmot/API-Flow.git | ||
| cd API-Flow | ||
| make install |
There was a problem hiding this comment.
Also the target make install does not exist.
|
@philsturgeon I believe the import statement needs to be: const ApiFlow = require('api-flow').default; // if from npm
const ApiFlow = require('./dist/node/api-flow.js').default; // if from `make runners TARGET="node"`i.e. add the At this point, I'm able to do a transform - notwithstanding some issues with AMD modules ( |
|
Thank you for replying @MikeRalphson! My debugging got me that far, I just get a different error: Content of that script file is: |
|
@philsturgeon did you use the package from npm, or build the code yourself as per this comment? Your script works fine / gets past that point here with the copy of API-Flow I've built from source. You could try adding const util = require('util')
console.log(util.inspect(ApiFlow))after the |
|
@MikeRalphson doh! Ok, I missed that reply from @JonathanMontane. I don't want that thread turning into a support one, but here is appropes for that. I skipped the When I use the example code from Jonathans comment, I get: |
|
@philsturgeon don't you just love webpack? There's no way of matching up line numbers between our builds unless we have the exact same order of directories in our Adding |
|
I was running v8.0.0 and now I'm on v7.4.0 via nodenv. My yarn was 0.24.1 and now it's v1.1.0. Rebuilt everything and I'm getting the same error about I tried adding |
|
Commenting out the offending What the heck is going on :D |
|
@philsturgeon Your issue mystified for a long while until I realized there's a dumb error in the webpack.config file of the webworker. change to alternatively, just use |
|
That makes sense, as I was building for |
|
Thank you for all the help! I did multiple targets in the first place because I wasn't sure which I needed (another point I'll add to the README). Since then I'd been doing just Deleting I'm just using your example @JonathanMontane so I'm not sure what is causing this. |
|
@JonathanMontane hey did you see my reply? Life is still terrible! :) |
|
@philsturgeon sorry for the late reply, I've been swamped. I am a bit stumped. Can you try adding a |
|
|
@philsturgeon Alright this is weird, but hopefully, we can solve this. It seems that the environment that is used is the web environment instead of the node environment for some reason. Can you check your If the file match, then maybe there's an issue with your node environment file directly. In that case, can you check that the file in If that's not the case, then I suppose the issue is with the Webpack resolver that fails for some reason, and then I'm clueless. |
|
You got it on the first throw! I'm seeing this in api-flow-config: Here's everything I did to get there, deleting everything and starting again: In previous iterations I think I'd done yarn and make in the wrong order and got a bunch of warnings, but this time I got it all 100% right aaaaand I'm still getting '../../src/environments/web/Environment` all up in there. Thanks for helping me with this!! |
|
@philsturgeon Glad to see it finally worked out for you. Sorry that it took so long to fix though. |
|
Ahh well no it's not resolved, I changed that line of code but I'm struggling to rebuild. I ran Next step was deleting I'd like to document the flow for a full rebuild, as I have no idea what to do now. Tried I deleted everything and started again and still |
|
HUZZAH! Ok, for some reason a previous attempts had been placing the dist folder in Now my script has: ALL GOOD! Updating my PR with instructions from my history so new folks don't get as lost and sad. Please commit anything you discovered as bugs during this thread. |
|
Actually now I'm getting I don't understand this workflow. I want to learn it and document it, but... 🤷♂️ |
|
@philsturgeon I don't have the hand on this repository anymore, so I am as stuck as you when it comes to updating it (you can see my fork for a more frequently updated version). However, you're on the right track here, and you just have to add a couple of lines to one files and you'll be good to go. Here's a bit of background knowledge so that you understand how everything works and you'll see that it's not that complex, it's just that this library had to work in many conflicting environments in a quite modular way. A Quick rundown of how API-Flow worksThere are 5 core concepts:
The Environments give methods to handle I/O ops that are used by the Loaders to fetch the original resource and all its associated resources, which are normalized and then passed to the Parsers, which convert the data into the Internal Model, which in turn is transformed into an output format by Serializers. EnvironmentsThese files contain wrappers for I/O operations in the different environments as a unified interface so that other parts of the library can forget about where they are run. This allows the library to be run in Node, the web, in web workers, and even JavascriptCore. You can find these files under LoadersThese files contain small methods that fetch the original resource from its uri, analyzes it and fetches all the other resources that this file may require. This is also the place where you can reduce the variability in your input, so that you have an easier time writing your parser afterwards. For example, swagger 2 can have implicit hostnames based on where the file is located. Implicit information generally doesn't translate well in other formats, so we make the host explicit at this stage. Another example would be the postman collection v2 format, where you can basically write a uri in about 10 different ways. Handling all these cases every time you encounter a URI while parsing the file would be a pain, and a good way to add errors to your code, so we normalize the URI scheme at this step. You can find these files under Parsers, Internal Model and SerializersThese are fairly easy to understand to be honest. How everything is bound togetherOnce you have all these bits that exist, you need to bind them together. This is where the core library (found in However this core file needs to load the correct dependencies depending on the environment it is running in. For instance, for the web, it needs the So in order to have as much liberty as possible while avoiding duplicating code, I chose to create simple config files, that are just imports/exports of all the specific files that you want in that specific setup. These files can be found in the Why Postman isn't working in Node (and how to resolve it)Now for why you don't seem to be able to convert from or to Postman collections in Node: It's quite simple, if you look at the As for why Postman isn't included, it's pretty simple. I forgot to add it. This library is mainly used inside Paw, rather than Node and the Postman format is one of the last formats I added to the library, so I forgot to add it to all the environments. I apologize for the inconvenience. Finally, Once you feel like you've got the hang of how everything is arranged, please feel free to create another config that suits exactly your needs (for instance that includes only postman and swagger, which can drastically reduce bundle size). What format name to useyou said you found I definitely agree that there's some effort to be made about the onboarding process though. Thank you for your patience anyway. |
|
Hey @JonathanMontane! You are awesome, this reply is fantastic, and I'm really grateful. I'm working with your fork as clearly theres a bunch of fixes in there, and that's a great place to start. Your outline of the arch of this app is amazing. I've created a PR to your repo with some fixes I needed to get things working, and now everything works. I'll keep playing around with your fork and try to get my solution to production, and when its done I'll update the README PR with some tips to newcomers on how stuff actually works. |
|
Seeing as this thread turned into a Phil Sturgeon Support Thread, I'm closing this for the more concise #147. Thanks to everyone that helped. Beers on me in NYC. 👍 |
3 participants
I'm excited about API Flow, but the README had me installing from source with me only noticing I could just yarn install later. I think the default for most folks is installing the package, not building from source.
I've also added
const path = require('path');as it was erring before that.Still, this is giving me trouble:
I'd love to get the README in line with how things work, just gimme some hints! :)