With our new API documentation we have switched from Swagger UI to Scalar Viewer. The reason for this is that the Swagger UI has reached its limits with the new API documentation.

The API documentation itself is based on OpenAPI 3.0.1 and can be found in the index.yaml file.

The Scalar Viewer itself uses the file openapi-bundled.json which is generated from the index.yaml file. The generation of the openapi-bundled.json file can be done with the following command:

npx @scalar/cli document bundle index.yaml -o openapi-bundled.json

We use a self-hosted version of Scalar to be independent from public CDNs. In case you want to update to a newer version, please delete the scalar-assets directory first. Now downloaded the latest version as zip or tar.gz from https://www.jsdelivr.com/package/npm/@scalar/api-reference

Unzip the file api-reference-<version>.tgz and copy the content of package/dist to the scalar-assets directory.

Thats all.

This repository contains all files required to run a version of the documentation. It it as simple as starting a nginx webserver in the root directory of this repository:

docker run --rm -v $PWD:/usr/share/nginx/html:ro -v $PWD/nginx-example.conf:/etc/nginx/conf.d/default.conf:ro  -p 80:80 --name scalar-ui nginx

The legacy Swagger UI is still available through the index_swagger.html file.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

https://swagger.io/docs

https://inspector.swagger.io

Start webserver over project repository, browse at http://localhost:80 You can also browse to the project repository directory using any common webserver.

docker run --rm -v $PWD:/usr/share/nginx/html:ro -v $PWD/nginx-example.conf:/etc/nginx/conf.d/default.conf:ro -p 80:80 --name swagger-ui nginx

Run the commands in the repository root directory.

Make sure, that the ports 80 and 81 are not used yet!

docker run -v $PWD:/usr/share/nginx/html:ro -v $PWD/nginx-example.conf:/etc/nginx/conf.d/default.conf:ro -d -p 80:80 --name swagger-ui nginx
docker run -d -p 81:80 --name swagger-editor swaggerapi/swagger-editor

Open http://localhost:81/?url=http://localhost:80/index.yaml to load the current spec into the editor.

Note:

• The swaggerapi/swagger-editor image no longer honors the SWAGGER_FILE/URL env vars documented upstream, and listens on container port 80 (not 8080) — use the ?url= query parameter shown above instead.
• Errors like Semantic error at paths./commands/edit/{commandId}.json can be ignored if they are triggered because of a path value like {commandId}.
• Copy the content of the edited index.yaml to the original file in your IDE to save your changes persistent

docker start swagger-editor swagger-ui

docker stop swagger-editor swagger-ui

docker rm swagger-editor swagger-ui

1. Start the swagger-editor docker container as described with your custom repository path
2. Start the nginx docker container as described with your custom repository path
3. Open the repository in your IDE
4. Copy the content of the index.yaml in the swagger-editor web console
5. Build a new section (e.g. services/newfeature.json) in the index.yaml in the swagger-editor web console
6. After finishing the section (if it works), add the new section to the "real" index.yaml in your IDE. Replace the section contents with a new $ref url.
7. If you created a new section, create a new file in the "external" folder with the name of your section and past the contents. (see following scheme example)
8. If your section already exists, add your contents to the existing section file in the "external" folder. (see following scheme example)
9. Save the files and validate in the swagger-ui that your changes are working

Run the repository checks from the project root:

python3 scripts/validate_spec.py
python3 scripts/audit_frontend_endpoints.py /path/to/openITCOCKPIT-frontend-angular-5.6.1
python3 scripts/audit_contract_completeness.py /path/to/openITCOCKPIT-frontend-angular-5.6.1

Use the exact Angular 5.6.1 tag, not a newer development checkout. The endpoint audit reports the static Angular translation asset as missing; /a/assets/i18n/{lang}.json is intentionally not an API operation. The contract-completeness audit additionally checks success/error responses, request bodies, parameter schemas and generator failures.

Concrete Angular response contracts can be regenerated with ts-json-schema-generator:

python3 scripts/generate_typescript_contracts.py \
  /path/to/openITCOCKPIT-frontend-angular-5.6.1 \
  --generator /path/to/ts-json-schema-generator

Generated contracts preserve explicit frontend uncertainty. Calls without a concrete response type are completed from the matching 5.6.1 backend controller; no response is left with an empty JSON schema.

Request-body contracts use the same TypeScript generator:

python3 scripts/generate_typescript_requests.py \
  /path/to/openITCOCKPIT-frontend-angular-5.6.1 \
  --generator /path/to/ts-json-schema-generator

Angular services often pass HttpClient a typed params method argument, or a copy/transform of one (JSON.parse(JSON.stringify(params)), {...params}, Object.assign({}, params), or a plain alias), as the request's params option. Those query parameters live in a different call argument than the URL template the other generators inspect, so they need their own pass:

python3 scripts/generate_query_parameters.py \
  /path/to/openITCOCKPIT-frontend-angular-5.6.1 \
  --generator /path/to/ts-json-schema-generator

It resolves the params expression back to its declared TypeScript type (following the copy/alias chain above) and adds the type's own fields as in: query parameters, skipping any name already covered by an inline parameter or a $ref to a shared components.parameters entry.

For JSON responses that have no concrete Angular type, top-level response fields can be extracted from the matching openITCOCKPIT 5.6.1 CakePHP controllers. Plugin operations can only be completed when the corresponding plugin source is present in that backend checkout.

python3 scripts/generate_backend_contracts.py \
  /path/to/openITCOCKPIT-5.6.1-with-module-controllers \
  --allow-wizard-family-inference

The inference flag is limited to four optional, separately licensed wizard POST responses. They are explicitly marked release-family-pattern-inferred; all other generated backend response roots come from delivered 5.6.1 controllers.

Finally, fill still-open path and query parameter schemas from Angular method types and documented naming conventions:

python3 scripts/complete_parameter_schemas.py \
  /path/to/openITCOCKPIT-frontend-angular-5.6.1 \
  --refresh-generated
python3 scripts/complete_error_responses.py
python3 scripts/prune_frontend_operations.py \
  /path/to/openITCOCKPIT-frontend-angular-5.6.1

The generated operations record their provenance and confidence in x-* extension fields. Run both validation commands again after regeneration.

requests:
  existingfeature:
    post:
    		..........
  newfeature:
    get:
    		..........

components:
  schemas:
    newfeatureResponse:
      ...........

Add the following lines to the webserver configuration of an openITCOCKPIT 4 instance.

add_header Access-Control-Allow-Origin "*";
add_header Access-Control-Allow-Methods "GET, POST, DELETE, PUT, PATCH, OPTIONS";
add_header Access-Control-Allow-Headers "Content-Type, Authorization";

if ($request_method = OPTIONS ) {
    return 200;
}

No longer needed. swagger-api/swagger-editor#2072 merged in 2020, and the current official swaggerapi/swagger-editor image works directly — see the ?url= instructions in the Development setup section above.

This repository vendors Swagger UI static files in assets/.

Use the helper script to update to a specific swagger-ui-dist release:

bash scripts/update_swagger_ui.sh 5.17.14

The script updates:

• assets/js/swagger-ui-bundle.js
• assets/js/swagger-ui-standalone-preset.js
• assets/js/swagger-ui.js
• assets/css/swagger-ui.css
• oauth2-redirect.html
• matching precompressed *.gz files

After updating, validate and deploy as usual:

python3 scripts/validate_spec.py