There are only ugly HTML pages as download (HTML, HTML2 and dynamic all ugly), but the site, eg. edited https://app.swaggerhub.com/apis/{user}/{project}/{version}
(and many others!) offers pretty HTML interface... How to download this pretty HTML?
Complete and autonomous HTML code (file or zip of files).
I have a good and valid swagger.yaml or swagger.json file of my API, so another solution is to run a open sourse (plug and play!) tool with my API-description file.
The pretty:
The ugly:
The "pretty interface" on your screenshot is Swagger UI. It's free and open-source. There's a demo at http://petstore.swagger.io, where you can load your own YAML/JSON files from an URL and see how they would be rendered.
To use Swagger UI locally:
Go to https://github.com/swagger-api/swagger-ui and download the repository as ZIP:
Edit the dist\index.html file and change the line
url: "http://petstore.swagger.io/v2/swagger.json",
to the URL of your Swagger .json or .yaml file, e.g.
url: "http://api.mysite.com/swagger.json",
(Optional) Add/change other configuration parameters in the SwaggerUIBundle initialization code in dist\index.html.
Open the dist\index.html file in your browser to preview your API docs.
Note: If the spec does not load or "try it out" does not work, you probably need to enable CORS on the your server. See https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/cors.md and https://enable-cors.org.
Upload the files from the dist folder somewhere to your server - and now you have pretty API docs too!
Alternatively, SwaggerHub (which you mentioned) provides cloud hosting for Swagger specs among other things, and has Swagger UI integrated. You can import your Swagger .json/.yaml files there and have your API docs hosted on SwaggerHub. A free plan is available.
Thanks to #tleyden at swagger-ui/issues for good clues!
Use the index and assets folder of this project, https://github.com/okfn-brasil/swagger-ui-html
Related
Is there a way to download docs for projects in markdown or plaintext format? The download menu offers only rendered formats that are much harder to parse.
I can try to write a script that goes to source repos and tries to build it, but each repo might have a different build process and it's more resource intensive.
I have swagger files with URLs like https://gitlab.com//blah/blah/Orders_Swagger.json. I'm building some documentation that links to these files; that works fine. Gitlab renders the page with nice formatting. But some swagger files have dozens of APIs and sometimes I want to reference a specific, critical API, not just send the user to the top of the page.
Swagger UI supports a "deepLinking=true" configuration parameter. It is set to false by support. Gitlab embeds Swagger UI, but does not provide a way to set this parameter, so it is off at the server level.
However, you can enable it by passing a parameter in the URL: &deepLinking=1
Thus, a full, API-specific URL will look like this:
https://gitlab.com/company/blah/blah/Swagger.json?deepLinking=1#/section/targetApiName
I want to host a json file on artifactory repo.
Currently if i go to the link for the file it directly downloads.
But i want it to be shown as a file like a webserver.
Is that possible in artifactory ?
Can it work as a webserver for hosting single files ?
In order to achieve your use case, you need to enable content browsing option in your Artifcatory repository. You can find the details here:
Please be aware this may not work for all the file types(for json it should) as it's based on the mime types configured for the Artifactory application.
You can view any file or artifact from the Artifactory UI (tree browsing) or with native list browsing.
See more information about file browsing here and here.
I'm developing a node-red application right now that uses a html response. The html uses google maps, visual indicators and websockets. It is very hard to debug this system through node-red's little html editor. Is there a way to edit the html file through any normal editor (e.g. vs code) and then deploy the application again to see the effect ?
One solution that came to my mind was to read from an external file using the file node and return it as html, put I don't know if that works. Is there a better way ?
You can create and edit static resources (html/css files etc) however you'd like and then serve them from Node-RED.
You have two options for serving static content:
create corresponding HTTP In -> File In -> HTTP Response flows for each file you want to serve
or use the httpStatic property in your settings.js file to identify a directory whose content should be automatically served by the runtime.
I have a basic webpage built, and a Swagger document JSON file of my API. I am unsure of how to actually add the data from the document to the website so that it can be browsed.
I want to build hosted documentation for the API.
This is the example given by Swagger: http://petstore.swagger.wordnik.com/#!/pet/addPet
Do I just download Swagger UI and use it in conjunction with the JSON file.
But I am unsure on to achieve this. Any advice on how to go about creating something like this would be very helpful.
Swagger-ui is basically a set of static files you can host on your server to display your API.
Unless you may any major changes, you just need to copy the contents of the /dist folder to your server and host it as part of your application (or static website, doesn't matter).
The SwaggerUi object can be customized to your needs, including the URL of the spec you're hosting.
Keep in mind that if you don't host the ui and spec on the same server, (that is, same host and same port), you need to enable CORS.