How to run Swagger 5 locally

[CodehunterWorks]

Q&A

• OS: Linux
• Browser: Firefox
• Version: 140.0.4
• Method of installation: dist assets
• Swagger-Editor version: 5.0.0-alpha.111
• Swagger/OpenAPI version: Swagger 5.0, OpenAPI 3.1

How can we help?

Hello!

At first, many thanks for developing Swagger Editor which is so a useful tool for my daily work! Today I tried to clone the GIT repo for the v5 from https://github.com/swagger-api/swagger-editor/archive/refs/tags/v5.0.0-alpha.111.zip and run it locally. For v4 it was simply: Open the index.html and all is fine. But with v5 I found an index.html in the ./public folder. When I open it in the browser, the only thing I see is:

Swagger Editor
%REACT_APP_VERSION%
Loading...

Please note that I'm not familar with React and npm and so on. My focus is on writing API YAML documentation. Please don't laugh at my clumsy attempt to run v5 locally. My hope is anyone can advise me to get it running.

PS: I know there is a running v5 online. But the docs which I need to edit are written for OAPI 3.1 and our employers security guidelines prohibits such online tools for work with our internal stuff.

Greets
Cody

[CodehunterWorks]

Update: I'm some little steps further...

1. npm install fails because some IPv6 glitches -> disabling IPv6 for my eth conn has solved it
2. downloaded cra from https://github.com/swagger-api/swagger-editor-cra/ and placed it in the ./create-react-app folder
3. installed typescript because its missed: npm install -g typescript --> whoops: it installs 5.8.0 but npm run build says max. 5.2.0 is supported for Swagger, so npm uninstall typescript and npm install --save-dev typescript@5.2 then running npm run build again
4. now npm run build is running completly through and I found an new index.html and some other assets in the ./build subfolder. When I open this index.html in Browser, now I see this:

Swagger Editor
5.0.0-alpha.111
Loading...

After then, I saw this in the README.md:

 $ npm i stream-browserify --save-dev
 $ npm i https-browserify --save-dev
 $ npm i stream-http --save-dev
 $ npm i util --save-dev
 $ npm i buffer --save-dev
 $ npm i process --save-dev

So I tried this and I got some errors that typescript 5.2 is too new. So npm uninstall typescript again and npm install --save-dev typescript@3.2.1 then the installs above does run properly. After then, I tried npm run build again. It runs some time longer as before, then I got 5106 errors like this:

node_modules/@types/babel__traverse/index.d.ts:321:9 - error TS1110: Type expected.

After then I blindly guessed that these errors are caused by incorrect typescript version again. Therefore one more time npm uninstall typescript and npm install --save-dev typescript@5.2 again, then run npm run build. And voila, it runs completly through without errors.

But in the Browser the ./build/index.html file shows furthermore:

Swagger Editor
5.0.0-alpha.111
Loading...

Finally, I found the solution :-) When opening ./build/index.html I saw an error in the Browser Console that file:///static/js/main.0f5cc781.js could not loaded. It seems like an absolute path issue. To solve this, I set up an lighttpd vhost "swagger.localhost" with a doc root directly to the /path/to/my/swagger/folder/build and opened the url http://swagger.localhost/index.html.

Whooosa! Swagger v5 is working locally! But this task was very heavy. This is nothing for someone who wants simply use Swagger v5. I ask myself: Is there eventually an pre-compiled v5 build downloadable as ZIP file?

[robert-hebel-sb]

Hey @CodehunterWorks, thanks for reaching us! We are aware of the complex setup process for swagger-editor@next. We are working on replacing CRA with a modern solution. Regarding TypeScript issues you have encountered, are you interested in providing a PR to make the setup process easier for new developers?

[CodehunterWorks]

Hey @CodehunterWorks, thanks for reaching us! We are aware of the complex setup process for swagger-editor@next. We are working on replacing CRA with a modern solution. Regarding TypeScript issues you have encountered, are you interested in providing a PR to make the setup process easier for new developers?

Hello Robert!

For me its less a question of developing Swagger itself. I develop REST/JSON APIs and Interfaces. Sometimes third parties send me their OAPI docs. Now I got an OAPI 3.1 based doc for first time. Swagger v5 seems to be the only solution who renders such 3.1 docs properly. Older v4 shows a lot of parsing errors. Now I'm in the uncomfortable situation that I must use v5-alpha for productive purposes. I'm aware about the implications but I see no other solution.

My wish would be: After my quick-and-dirty compiling (described above) I found all neccessary assets of a working Swagger v5 in the ./build subfolder. My learning process took about 2 hours and this was only possible because I already had extensive experience in lighttpd, bash etc. Many others may not have such experiences. It would be very helpful when the contents of the ./build subfolder (in my case which I compiled myself) would be compiled from time to time by a buildserver and make downloadable as ZIP file. Simply downloading, unpacking into a folder, opening index.html.

As far as I can see, v5 works fine for me. Maybe some features are incomplete but I see no showstoppers. Good work!

Greets
Cody

[cka121]

Hey @CodehunterWorks, It's great to hear v5 is working fine for you now.

Unfortunately, we won't be able to provide downloadable zip file as a workaround. We want to let you know that soon we will be replacing CRA with modern and streamlined solution. We believe this tranisition will resolve the current build issues and provide more robust development experience.

[cka121]

We appreciate your patience and understanding. I will be closing this ticket now. Please don't hesitate to reach out if there is any further issues.

[CodehunterWorks]

@cka121 I'm ok with that. For the moment my setup is working properly. Wondering why some 3rd parties are using OAPI 3.1 for production. They use Swagger 5 (online version) too, as far as I know.