How To Install Swagger Ui On Windows

1. I'd Rather Be Writing
2. Learn API Physician
3. OpenAPI spec and generated reference docs

Swagger UI tutorial

Terminal updated: Apr 04, 2022

Swagger UI provides a display framework that reads an OpenAPI specification document and generates an interactive documentation website. The post-obit tutorial shows you how to integrate an OpenAPI specification document into Swagger UI.

For a more than conceptual overview of OpenAPI and Swagger, see Introduction to the OpenAPI specification, or see this article I wrote for ISTC a few years ago: Implementing Swagger with API docs (PDF). For a step-by-step tutorial on creating an OpenAPI specification document, run into the OpenAPI tutorial. Or for an easier approach using a visual editor to create the OpenAPI spec, see Getting started tutorial: Using Stoplight Studio to create an OpenAPI specification certificate.

• Swagger UI overview
• Get familiar with Swagger UI through the Petstore demo
  • Brand a request
  • Verify that your pet was created
• Some sample Swagger UI dr. sites
• Activity: Create a Swagger UI brandish with an OpenAPI spec document
• Activity: View local OpenAPI file in Swagger UI
• Configuring Swagger UI parameters
• Challenges with Swagger UI
• Troubleshooting problems with Swagger UI
• Embedding Swagger UI inside an existing site
• Key terms

Swagger UI overview

Swagger UI is one of the most popular tools for generating interactive documentation from your OpenAPI document. Swagger UI generates an interactive API console for users to quickly larn most your API and experiment with requests. Additionally, Swagger UI (which is an actively managed project with an Apache 2.0 license) supports the latest version of the OpenAPI spec (three.ten) and integrates with other Swagger tooling.

For definitions of common terms, run across Primal terms at the end of this commodity.

Become familiar with Swagger UI through the Petstore demo

To get a better understanding of Swagger UI, let's explore the Swagger Petstore example. In the Petstore example, the site is generated using Swagger UI.

The endpoints are grouped as follows:

• pet
• store
• user.

Qualify your requests

Before making any requests, you would commonly authorize your session by clicking the Authorize button and completing the information required in the Authorization modal pictured beneath:

The Petstore example has an OAuth ii.0 security model. Notwithstanding, the authorization lawmaking is just for demonstration purposes. In that location isn't whatever real logic authorizing those requests, and so you can simply close the Authorization modal.

Make a request

Now allow's brand a asking:

1. Expand the POST Pet endpoint.

2. Click Try it out.

   

   After you lot click Try it out, the example value in the Request Body field becomes editable.

3. In the Instance Value field, change the outset id value to a random integer, such as 193844. Change the 2d proper noun value to something y'all'd recognize (your pet'southward proper name).

4. Click Execute.

   

   Executing a sample Petstore request

   Swagger UI submits the request and shows the curl that was submitted. The Responses section shows the response. (If yous select JSON rather than XML in the "Response content type" drop-downwards box, the response'due south format will be shown in JSON.)

   

Verify that your pet was created

1. Aggrandize the Become /pet/{petId} endpoint.
2. Click Try it out.
3. Enter the pet ID yous used in the previous functioning. (If you lot forgot it, wait back in the Post Pet endpoint to bank check the value.)
4. Click Execute. You should meet your pet's name returned in the Response section.

Some sample Swagger UI md sites

Before we go into this Swagger tutorial with another API (other than the Petstore demo), bank check out a few Swagger implementations:

• Reverb
• VocaDB
• IBM Watson IoT Admin REST APIs
• The Movie Database API

Some of these sites look the same, but others, such as The Movie Database API and Zomato, take been integrated seamlessly into the rest of their documentation website.

Looking at the examples, you'll notice the documentation is short and sweet in a Swagger implementation. This brevity is considering the Swagger display is meant to be an interactive experience where you can try out calls and meet responses — using your own API central to come across your own information. It's the learn-by-doing-and-seeing-it approach. Also, Swagger UI only covers the reference topics of your documentation. The conceptual topics are ordinarily covered in a divide guide.

Activity: Create a Swagger UI display with an OpenAPI spec document

In this activity, you'll create a Swagger UI display for an OpenAPI specification document. If you're using 1 of the pre-built OpenAPI files, you can see a demo of what we'll build here: OpenWeatherMap Swagger UI.

Demo of Swagger UI rendering an OpenWeatherMap OpenAPI specification certificate

First, you'll brand sure you can view Swagger locally. Then you'll switch the Petstore OpenAPI document URL with an OpenWeatherMap OpenAPI document URL.

1. Go to the Swagger UI GitHub project.

2. Click Clone or download, and then click Download Cipher. Download the files to a convenient location on your computer and extract the files.

   The only folder you lot'll be working with in the downloaded zip is the dist binder (short for distribution). Everything else is used simply if yous're recompiling the Swagger files, which is beyond the scope of this tutorial. (If desired, you lot can drag the dist binder out of the swagger-ui-chief folder then that it stands alone.)

3. In your Chrome browser, press Cmd+O (Mac) or Ctrl+O (Windows), browse to the dist folder, and select the index.html file,

   You should see the Petstore Swagger content. Now y'all'll customize the OpenAPI spec file with another file.

4. Inside your dist folder, open up index.html in a text editor such as Sublime Text.

5. Look for the post-obit code:

                                     url                  :                  "                  http://petstore.swagger.io/v2/swagger.json                  "                  ,                              

6. Change the url value to an online spider web URL to your Swagger file. For example: https://idratherbewriting.com/learnapidoc/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml. Then relieve the file.

   If the url reference isn't to an online URL, Swagger UI volition create an CORS (cross-origin resource sharing) fault. To view Swagger UI with a local OpenAPI file, y'all can run a elementary Python server locally to simulate a spider web server (this requires y'all to install Python).

7. Refresh the index.html file in your Chrome browser. The content should testify the OpenWeatherMap API content instead of Swagger Petstore content.

   When y'all're ready to publish your Swagger UI file, yous just upload the dist folder (or whatever you want to call it) to a web server and go to the index.html file. For example, if you called your directory dist (leaving it unchanged), you lot would get to http://myserver.com/dist/.

   For more instructions in working with Swagger UI, see the Swagger.io docs.

Activeness: View local OpenAPI file in Swagger UI

In order to view a local OpenAPI file (rather than an OpenAPI file hosted on a web server), you lot'll demand to run an HTTP server on your computer. This is because CORS (cross-origin resource sharing) security restrictions in Chrome will block Swagger UI from running. Swagger UI needs to load on a web server to fulfill the security requirements.

You tin create a local web server running on your computer through Python's SimpleHTTPServer module. Mac has a system version of Python installed by default, only Windows computers will demand to install Python.

Windows: Run the Python uncomplicated HTTP server

1. Download and install Python 3x.

   When you install Python, be sure to select the check box that says "Add together Python 3.7 to PATH." This bank check box isn't selected by default. If you don't select information technology, your command prompt won't recognize the discussion "python".

   

   Add Python 3.vii to PATH

2. After installing Python, close your command prompt and reopen it.

3. In your command prompt, browse to the Swagger UI dist directory.

   To browse in the Windows command prompt, type cd <binder name> to move into the binder. Type cd .. to motion up a directory. Type dir to run into a list of the current directory's contents.

   If y'all're having trouble locating the dist directory in the command prompt, try this play tricks: type cd, printing the spacebar, and then drag the dist folder directly into the control prompt. The path will be printed automatically.

4. After you've navigated into the dist folder, launch the server:

   If this command doesn't work, try it without the three:

   The server starts:

                   Serving HTTP on 0.0.0.0 port 8000                  (http://0.0.0.0:8000/)                  ...                              

   (If your Command Prompt doesn't recognize python, and then you lot probably need to add Python to your PATH. Instructions for doing that are outside the telescopic of this tutorial.)

5. Go to http://localhost:8000/ in your address bar. This address lets you view the local web server.

   By default, spider web servers default to the index.html file in the directory, so it will show the Swagger UI file automatically. If the browser doesn't straight to index.html, add it manually: http://localhost:8000/index.html.

   To stop the server, press Ctrl+C in your command prompt. If you closed your Command Prompt earlier stopping the service, type ps, discover the process ID, then type kill -9 <process ID>.

Mac: Run the Python simple HTTP server

1. In your terminal, browse to the Swagger UI dist directory.

   To scan in your terminal, blazon cd <folder proper name> to motion into the folder. Type cd .. to motion upward a directory. Type ls to see a listing of the current directory's contents.

   If you're having trouble locating the dist directory in the control prompt, endeavor this trick: type cd, press the spacebar, and then drag the dist folder directly into the command prompt. The path volition exist printed automatically.

2. Since Mac already has Python, yous tin but run the following in your terminal to launch simple server:

   If this command doesn't work, endeavour it with the 3 in instance you already have Python3 installed:

   The server starts:

                   Serving HTTP on 0.0.0.0 port 8000                  (http://0.0.0.0:8000/)                  ...                              

3. Go to http://localhost:8000/ in your address bar. This address lets you lot view the local web server.

   By default, web servers default to the index.html file in the directory, so it volition show the Swagger UI file automatically. If the browser doesn't direct to index.html, add it manually: http://localhost:8000/index.html.

   To stop the server, press Ctrl+C in your command prompt. If yous closed your Command Prompt before stopping the service, type ps, find the process ID, then type kill -nine <process ID>.

For more details on using the Python simple server, run across How do you set up a local testing server? for more details.

Customize the OpenAPI file

By default, SwaggerUI has the Petstore OpenAPI certificate configured in the url parameter in the index.html file. You demand to bandy in your local file instead.

1. Download the following OpenAPI document (correct-click the link and salvage the YAML file to your desktop.): https://idratherbewriting.com/learnapidoc/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml

2. Elevate your OpenAPI specification file, openapi_openweathermap.yml, into the dist binder. Your file structure should look as follows:

   ├── dist │   ├── favicon-16x16.png │   ├── favicon-32x32.png │   ├── index.html │   ├── oauth2-redirect.html │   ├── swagger-ui-bundle.js │   ├── swagger-ui-bundle.js.map │   ├── swagger-ui-standalone-preset.js │   ├── swagger-ui-standalone-preset.js.map │   ├── swagger-ui.css │   ├── swagger-ui.css.map │   ├── swagger-ui.js │   ├── swagger-ui.js.map │   ├── swagger30.yml │   └──              openapi_openweathermap.yml            

3. Within your dist folder, open up swagger-initializer.js in a text editor such as Sublime Text.

4. Look for the post-obit code:

                                     url                  :                  "                  http://petstore.swagger.io/v2/swagger.json                  "                  ,                              

5. Modify the url value from http://petstore.swagger.io/v2/swagger.json to a relative path to your YAML file, and so salvage the file. For example:

                                     url                  :                  "                  openapi_openweathermap.yml                  "                  ,                              

6. View the index.html file locally in your browser using the Python elementary server. For instance, become to http://0.0.0.0:8000/ or http://0.0.0.0:8000/index.html.

   If you go to the file path, such as file:///Users/tomjoht/Downloads/dist/index.html, you might encounter a message that says "Failed to load API definition" note in the JavaScript Panel that says "URL scheme must be "http" or "https" for CORS request." The SimpleServer simulates this http or https.

7. To stop the Python simpler server, printing Ctrl+C in your last or command prompt.

Configuring Swagger UI parameters

Swagger UI provides diverse configuration parameters (unrelated to the OpenAPI parameters) that you can apply to customize the interactive display. For example, you lot tin set whether each endpoint is expanded or collapsed, how tags and operations are sorted, whether to bear witness request headers in the response, whether to include the Models section subsequently the list of endpoints, and more.

We won't get as well much into the details of these configuration parameters in the tutorial. I just want to phone call attending to these parameters here for awareness.

If you look at the source of my Swagger UI demo (go to View > Source), you'll see the parameters listed in the // Build a system department:

                          // Build a arrangement              const              ui              =              SwaggerUIBundle              ({              url              :              "              openapi_openweathermap.yml              "              ,              dom_id              :              '              #swagger-ui              '              ,              defaultModelsExpandDepth              :              -              i              ,              deepLinking              :              true              ,              presets              :              [              SwaggerUIBundle              .              presets              .              apis              ,              SwaggerUIStandalonePreset              ],              plugins              :              [              SwaggerUIBundle              .              plugins              .              DownloadUrl              ],              layout              :              "              StandaloneLayout              "              })                      

The parameters in that location (e.chiliad., deepLinking, dom_id, etc.) are defaults. However, I've added defaultModelsExpandDepth: -1 to hide the "Models" section at the bottom of the Swagger UI display (because I think that section is unnecessary).

Y'all can too acquire near the Swagger UI configuration parameters in the Swagger documentation.

Challenges with Swagger UI

As you explore Swagger UI, you may notice a few limitations:

• At that place's not much room to describe in detail the workings of the endpoints. If you take several paragraphs of details and gotchas nigh a parameter, it's best to link out from the description to another folio in your docs. The OpenAPI spec provides a way to link to external documentation in both the paths object, the info object, and the externalDocs object
• The Swagger UI looks more often than not the same for each API. You lot can customize Swagger UI with your own branding, but information technology will require some more than in-depth UX skills. It is, however, relatively easy to change the color and image in the top navigation bar.
• The Swagger UI might be a dissever site from your other documentation. This separate output means that in your regular docs, y'all'll probably need to link to Swagger as the reference for your endpoints. You don't desire to duplicate your parameter descriptions and other details in ii different sites. Meet Integrating Swagger UI with the rest of your docs for strategies on unifying your reference docs and user guide.

Troubleshooting issues with Swagger UI

When you're setting upwardly Swagger UI, you might run into some issues. The following bug are the most common:

CORS issues:

If you lot have security correctly configured, but the requests are rejected, it could be due to a CORS (cross-origin resources sharing) event. CORS is a security mensurate that websites implement to make certain other scripts and processes cannot accept their content through requests from remote servers. See CORS Back up in Swagger UI'south documentation for details.

If the requests aren't working, open your browser's JavaScript console when you make the request and see if the error relates to cross-origin requests. If this is the error, inquire your developers to enable CORS on the endpoints. (To open the JavaScript Console, on Chrome on a Mac, go to View > Developer > Javascript Console; on Windows, click the carte du jour button (vertical ellipses) and get to More tools > Developer tools. So click the Console tab.)

Host URL issues:

The host for your exam server might be another reason that requests are rejected. Some APIs (like Aeris Conditions) require you lot to create an App ID that is based on the host URL where you'll be executing requests. If the host URL you registered is http://mysite.com, simply you're submitting the test from https://editor.swagger.io/, the API server volition reject the requests.

If you demand help, the Swagger Google Group is a helpful resource for troubleshooting.

Embedding Swagger UI inside an existing site

In addition to publishing your Swagger UI output as a standalone site, you tin can too embed the Swagger file within an existing site. See the following:

• Standalone Swagger UI Demo
• Embedded Swagger UI Demo

Since the Swagger UI site is responsive, it resizes well to fit into most whatever infinite. Withal, embedding Swagger into an existing site nevertheless looks like a website within a website.

Cardinal terms

Swagger

Refers to API tooling related to the OpenAPI spec. Some of these tools include Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub, and others. These tools are managed by Smartbear. For more tools, see Swagger Tools. "Swagger" was the original name of the OpenAPI spec, just the name was after changed to OpenAPI to reinforce the open up, not-proprietary nature of the standard. People sometimes refer to both names interchangeably (especially on older web pages), but "OpenAPI" is how the spec should exist referred to. For more on naming conventions betwixt OpenAPI and Swagger, see What Is the Difference Between Swagger and OpenAPI?.

OpenAPI

The official name for the OpenAPI specification. The OpenAPI specification provides a set of properties that can be used to describe your REST API. When valid, the specification document can be used to create interactive documentation, generate customer SDKs, run unit of measurement tests, and more. You can read the specification details on GitHub at https://github.com/OAI/OpenAPI-Specification. Nether the Open API Initiative with the Linux Foundation, the OpenAPI specification aims to be vendor neutral (many companies steer its development, not just one).

Swagger Editor

An online editor that validates your OpenAPI document against the rules of the OpenAPI specification. The Swagger Editor volition flag errors and give you lot formatting tips. Encounter Swagger Editor.

Swagger UI

An open up-source web framework (on GitHub) that parses an OpenAPI specification document and generates an interactive documentation website. Swagger UI is the tool that transforms your spec into the Petstore-similar site.

Swagger Codegen

Generates customer SDK lawmaking for a lot of different platforms (such every bit Java, JavaScript, Scala, Python, PHP, Ruby, Scala, and more than). The customer SDK code helps developers integrate your API on a specific platform and provides for more than robust implementations that might include more scaling, threading, and other necessary code. In general, SDKs are toolkits for implementing the requests made with an API. Swagger Codegen generates the customer SDKs in nearly every programming language. Encounter Swagger Codegen for more data. See also SDKs.

For more terms, see the Glossary.

42/161 pages complete. Simply 119 more pages to go.

Source: https://idratherbewriting.com/learnapidoc/pubapis_swagger.html

Posted by: colbertmaind1949.blogspot.com

Share this post