Swagger (OpenAPI) documentation missing

[jakubklimek]

See https://docs.google.com/presentation/d/1d1IBddgY8LRS5oXlocLBaXfbBs2lv76bXwZJvUabiP8/edit#slide=id.g7f91e5b4b8_0_58 and https://editor.swagger.io/. You have a postman collection. I will allow it, but try using swagger as well.

[SaNuelson]

@jakubklimek Thank you for the feedback, I've completely forgot about the documentation part of the assignment.

However, I'm not entirely sure how to make it work. I've followed the link in the slides to the swagger's online editor, cleared it and tried to import generated WADL file (downloaded and passed in as a file).

The file itself as well as the extended version (got from http://localhost:8080/RestContractorServer/webservice/application.wadl? and http://localhost:8080/RestContractorServer/webservice/application.wadl?detail=true respectively) are stored in the repo at 08-rest/generated-wadl/.

However, both of the files when passed into the editor via File > Import file result in error:

The mentioned line in both cases is

<doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 3.0.4 2022-02-08 17:22:15"/>

which is weird to me as the XML is automatically generated and seems to be a valid XML, even some XML validators I tried out saw no issue with the structure.

[jakubklimek]

The point here is to create the documentation manually. "Import from URL" is expecting the OpenAPI YAML file, not WADL.

[SaNuelson]

Thank you for the clarification.

I managed to get started quickly with the YAML and everything works great.

One issue I encountered thought is that I'm unable to execute these directly from the swagger editor.

I've come to find the issue comes down to how swagger wraps its request tokens in apostrophes, which don't get properly escaped in Windows.

E.g. executing current only method specified in yaml, generates a request:

curl -X 'GET' \
  'http://localhost:8080/RestContractorServer/webservice/contracts/info/201326592' \
  -H 'accept: application/json'

which yields

I've tried running swagger editor locally to make sure it's not an issue of access, but that encounters the same issue.

At the same time, running the URL in browser or via Postman works fine.

Finally I ran it on cmd.exe and worked out that running that curl really doesn't work. Stripping the apostrophes though, works. When adding verbose flag, the dump shows that the header actually contains 'GET' in the former call, which I assume is why the server doesn't respond correctly. Same issues occur when URL is wrapped in apostrophes.

Stripping the apostrophes from the URL and the GET works, as well as running it completely skipping the -X option.

I tried it also on WSL and there it seems apostrophes are correctly stripped, and even the swagger's generated request works fine.

I'm not sure if this is the exact cause of it, but all seems to indicate that.

[jakubklimek]

This seems just like a commandline escaping issue. I.e. for windows cmd, the parameters need to be in " instead of '. See e.g. in Chrome:

And the resulting cmd command:

curl "http://localhost:8080/lab08/hw8/eshop/shopping-cart/24" ^
  -H "sec-ch-ua: ^\^" Not A;Brand^\^";v=^\^"99^\^", ^\^"Chromium^\^";v=^\^"100^\^", ^\^"Google Chrome^\^";v=^\^"100^\^"" ^
  -H "accept: application/xml" ^
  -H "Referer: " ^
  -H "DNT: 1" ^
  -H "sec-ch-ua-mobile: ?0" ^
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" ^
  -H "sec-ch-ua-platform: ^\^"Windows^\^"" ^
  --compressed