8

localhost/swagger is loading as expected for me but remoteserver/swagger is having issues. Is it possible for me to save an offline copy of the swagger documentation that's generated? I can just send a zip file to a few users while I'm trying to debug the remote issue.

user9393635
  • 1,369
  • 4
  • 13
  • 32
  • 1
    https://www.httrack.com/ – Shloime Rosenblum May 02 '18 at 15:04
  • 1
    By "Swagger documentation", do you mean the OpenAPI/Swagger definition itself (YAML/JSON file), or interactive Swagger UI with "try it out" (like on http://petstore.swagger.io), or do you want a [PDF](https://stackoverflow.com/q/30217910/113116) or something else? The more specific you are, the easier it will be to suggest something. – Helen May 02 '18 at 16:18
  • Possible duplicate of [How to generate offline Swagger API docs?](https://stackoverflow.com/questions/34984820/how-to-generate-offline-swagger-api-docs), [Generate static docs with swagger](https://stackoverflow.com/q/26605217/113116), [Converting Swagger specification JSON to HTML documentation](https://stackoverflow.com/q/25800493/113116) – Helen May 02 '18 at 18:19
  • Does this answer your question? [How to export a Swagger JSON/YAML file from Swagger UI?](https://stackoverflow.com/questions/48525546/how-to-export-a-swagger-json-yaml-file-from-swagger-ui) – sashoalm Aug 14 '20 at 11:59

1 Answers1

15

There are lots of ways to provide API docs to your users if you for some reason cannot host Swagger UI yourself. All suggestions assume you have an OpenAPI (Swagger) definition, that is the YAML/JSON file. If you don't know the location of the YAML/JSON file, you can infer it from the Swagger UI web page.

In no particular order:

  1. Send the YAML/JSON file to your users and tell them to load it in http://editor.swagger.io in order to preview the API docs.

  2. Import your OpenAPI definition file into SwaggerHub and host your API docs there.
    Disclosure: SwaggerHub is made by the company I work for.

  3. Put your OpenAPI definition file on any public web server, e.g. create a gist on GitHub. Then you can render API docs by loading it into Swagger UI public demo, like so:

     http://petstore.swagger.io?url=YOUR_YAML_or_JSON_URL

If using a gist, make sure to specify a raw gist link (https://gist.githubusercontent.com/...). If using another hosting, make sure the hosting server supports CORS.

  1. "Pack" Swagger UI and your OpenAPI definition into a single dependency-less file as explained here, and send the resulting file to your users.

  2. Generate static HTML docs (not Swagger UI, but a static HTML page without "try it out"): load your OpenAPI definition into http://editor.swagger.io, then select the menu item Generate Client > html or html2 or dynamic-html.

The "Generate Client" feature uses Swagger Codegen, so you can also use the CLI version of the Codegen to generate the desired output.

  1. Want a PDF? It's possible to convert OpenAPI definitions to PDF.

See also:

Helen
  • 87,344
  • 17
  • 243
  • 314
  • It would be great to have option 3 with a URL not containing the word 'petstore'. I'm surprised one doesn't exist already as 'editor' is generic, so I was expecting something like 'ui' or 'view' as a subdomain to exist. – Jo P Mar 03 '19 at 11:27