api

frontend/web/api-doc/docs/development/scripts.md

@@ -0,0 +1,39 @@
+# Helpful scripts
+
+Any of the scripts below can be run by typing `npm run <script name>` in the project's root directory.
+
+### Developing
+Script name | Description
+--- | ---
+`dev` | Spawn a hot-reloading dev server on port 3200.
+`deps-check` | Generate a size and licensing report on Swagger UI's dependencies.
+`lint` | Report ESLint style errors and warnings.
+`lint-errors` | Report ESLint style errors, without warnings.
+`lint-fix` | Attempt to fix style errors automatically.
+`watch` | Rebuild the core files in `/dist` when the source code changes. Useful for `npm link` with Swagger Editor.
+
+### Building
+Script name | Description
+--- | ---
+`build` | Build a new set of JS and CSS assets, and output them to `/dist`.
+`build-bundle` | Build `swagger-ui-bundle.js` only (commonJS). 
+`build-core` | Build `swagger-ui.(js\|css)` only (commonJS).
+`build-standalone` | Build `swagger-ui-standalone-preset.js` only (commonJS).
+`build-stylesheets` | Build `swagger-ui.css` only.
+`build:es:bundle` | Build `swagger-ui-es-bundle.js` only (es2015).
+`build:es:bundle:core` | Build `swagger-ui-es-bundle-core.js` only (es2015).
+
+### Testing
+Script name | Description
+--- | ---
+`test` | Run unit tests in Node, run Cypress end-to-end tests, and run ESLint in errors-only mode.
+`just-test-in-node` | Run Mocha unit tests in Node.
+`test:unit-jest` | Run Jest unit tests in Node.
+`e2e` | Run end-to-end tests (requires JDK and Selenium).
+`e2e-cypress` | Run end-to-end browser tests with Cypress.
+`dev-e2e-cypress` | Dev mode, open Cypress runner and manually select tests to run.
+`lint` | Run ESLint test
+`test:artifact` | Run list of bundle artifact tests in Jest
+`test:artifact:umd:bundle` | Run unit test that confirms `swagger-ui-bundle` exports as a Function
+`test:artifact:es:bundle` | Run unit test that confirms `swagger-ui-es-bundle` exports as a Function
+`test:artifact:es:bundle:core` | Run unit test that confirms `swagger-ui-es-bundle-core` exports as a Function

frontend/web/api-doc/docs/development/setting-up.md

@@ -0,0 +1,37 @@
+# Setting up a dev environment
+
+Swagger UI includes a development server that provides hot module reloading and unminified stack traces, for easier development.
+
+### Prerequisites
+
+- git, any version
+- **Node.js >=16.13.2** and **npm >=8.1.2** are the minimum required versions that this repo runs on, but we recommend using the latest version of Node.js@16
+
+### Steps
+
+1. `git clone https://github.com/swagger-api/swagger-ui.git`
+2. `cd swagger-ui`
+3. `npm run dev`
+4. Wait a bit
+5. Open http://localhost:3200/
+
+### Using your own local api definition with local dev build
+
+You can specify a local file in `dev-helpers/swagger-initializer.js` by changing the `url` parameter. This local file MUST be located in the `dev-helpers` directory or a subdirectory. As a convenience and best practice, we recommend that you create a subdirectory, `dev-helpers/examples`, which is already specified in `.gitignore`.
+
+replace
+```
+url: "https://petstore.swagger.io/v2/swagger.json",
+```
+
+with
+```
+url: "./examples/your-local-api-definition.yaml",
+```
+
+Files in `dev-helpers` should NOT be committed to git. The exception is if you are fixing something in `index.html`, `oauth2-redirect.html`, `swagger-initializer.js`, or introducing a new support file.
+
+## Bonus points
+
+- Swagger UI includes an ESLint rule definition. If you use a graphical editor, consider installing an ESLint plugin, which will point out syntax and style errors for you as you code.
+  - The linter runs as part of the PR test sequence, so don't think you can get away with not paying attention to it!