Docs: Include REST API reference content from swagger.json #14607

oraNod · 2023-10-26T15:44:09Z

SUMMARY

Includes the swagger.json REST API reference as part of the docs build.

This PR does the following:

Updates RST and resources to include generated API docs.
Adds a Python script that fetches "swagger.json" from a "swagger-test" folder in the public s3 bucket.
Updates the docs build tox session to run the Python script before doing the sphinx-build.

The https://awx-public-ci-files.s3.amazonaws.com/swagger-test/swagger.json file is added as part of a RH internal Jenkins build. As a follow up it would be ideal to replace that Jenkins build with something similar to

awx/.github/workflows/upload_schema.yml

Line 47 in bef0a8b

- name: Upload API Schema

ISSUE TYPE

Bug, Docs Fix or other nominal change

COMPONENT NAME

Docs

AWX VERSION

N/A

ADDITIONAL INFORMATION

N/A

oraNod · 2023-10-26T15:47:01Z

I've used this to deploy on RTD from my fork. https://oranod-awx.readthedocs.io/en/latest/rest_api/api_ref.html

oraNod · 2023-10-26T15:56:47Z

Any opinions on naming the folder in the S3 bucket if this approach is OK? I went with swagger-test to try it out but if we go ahead we should likely change that to something else. Possibly swagger-json or swagger-docs or just plain docs.

Edit: I changed the folder to community-docs so it should be super clear what it is used for. We might also need to add some bits for the generated CLI reference to that same folder so it made sense to have a more generic name.

tvo318

Looks good to me!

oraNod · 2023-11-03T11:33:17Z

@TheRealHaoLiu @AlanCoding @thedoubl3j Hi, could one of you - or someone else - please take a look and let me know if you have thoughts or concerns? Thanks.

fosterseth · 2023-11-10T19:05:39Z

tox.ini

@@ -35,4 +35,5 @@ deps =
 -r{toxinidir}/docs/docsite/requirements.in
 -c{toxinidir}/docs/docsite/requirements.txt
 commands =
+ python {toxinidir}/docs/docsite/rst/rest_api/_swagger/download-json.py


any particular reason to use a python call here instead of curl or wget? Not very familiar with tox command limitations

hey @fosterseth thanks for the review and question. this really came down to the read the docs build moreso than tox. somewhat surprisingly neither wget or curl seemed to be available there. in an effort to make sure the build is consistent across environments the python call seemed like a good way to go.

fosterseth · 2023-11-10T19:09:00Z

also, would we be able to use schema.json directly? the only uploaded from this workflow

awx/.github/workflows/upload_schema.yml

Line 47 in bef0a8b

- name: Upload API Schema

what is the difference between schema.json and swagger.json?

oraNod · 2023-11-15T18:45:04Z

also, would we be able to use schema.json directly? the only uploaded from this workflow

awx/.github/workflows/upload_schema.yml

Line 47 in bef0a8b

- name: Upload API Schema

what is the difference between schema.json and swagger.json?

@fosterseth Thanks again for the questions. I did try to build the API reference with the schema.json but it didn't work as expected because it has additional data compared with the swagger file. I'm hopeful that we can tackle that as a follow up and simply extract the necessary bits from the schema though.

oraNod · 2023-11-15T18:45:29Z

Thanks for merging @TheRealHaoLiu

Fixed ldap url a bit and cleaned up a few things. Changed conditional back to adn rather than or and changed var back to password rather than username. fix wsrelay connection in ipv6 environments Fix: ansible#14511 Add alt-text codeblock to Images for Userguide: main_menu.rst Signed-off-by: Ratan Gulati <[email protected]> Revised the proposed Alt text for main_menu.rst Update insights.rst Update insights.rst Revised proposed alt text for insights.rst Updated images - Workflow Templates chapter of Userguide. Removed references to images that were deleted. Fix: ansible#14523 Add alt-text codeblock to Images for workflow_template.rst (ansible#14604) * add alt to images in workflow_templates.rst Signed-off-by: Ratan Gulati <[email protected]> * add alt to images in workflow_templates.rst Signed-off-by: Ratan Gulati <[email protected]> * Update workflow_templates.rst * Revised proposed alt text for workflow_templates.rst --------- Signed-off-by: Ratan Gulati <[email protected]> Co-authored-by: TVo <[email protected]> Added alt text for settings-menu.rst (ansible#14639) * Re-do for PR ansible#14595 to fix CI issues. * Added alt text to settings-menu.rst * Update docs/docsite/rst/common/settings-menu.rst Co-authored-by: Don Naro <[email protected]> --------- Co-authored-by: Hao Liu <[email protected]> Co-authored-by: Don Naro <[email protected]> Docs: Include REST API reference content from swagger.json (ansible#14607) Setting credential_type as required (ansible#14651) * Setting credential_type as required * Added test for missing credential_type in credential module * Corrected test assertion --------- Co-authored-by: Lucas Benedito <[email protected]> Replaced with larger graphic. (ansible#14647) Correctly handle case where unpartitioned table does not exist (ansible#14648) Set subscription type as developer for developer subscriptions. (ansible#14584) * Set subscription type as developer for developer subscriptions. Signed-off-by: Tong He <[email protected]> * Set subscription type as developer for developer subscription manifests. Signed-off-by: Tong He <[email protected]> * Remedy the wrong character to assign value. Signed-off-by: Tong He <[email protected]> * Reformat licensing.py by black. Signed-off-by: Tong He <[email protected]> --------- Signed-off-by: Tong He <[email protected]> issue ansible#14653 heading does not render correctly (ansible#14665) Adding the possibility to decode base64 decoded strings to Delinea's Devops Secret Vault (DSV) (ansible#14646) Adding the possibility to decode base64 decoded strings to Delinea's Devops Secret Vault (DSV). This is necessary as uploading files to DSV is not possible (and not meant to be) and files should be added base64 encoded. The commit is making sure to remain backward compatible (no secret decoding), as a default is supplied. This has been tested with DSV and works for secrets that are base64 encoded and secrets that are not base64 encoded (which is the default). Signed-off-by: Steffen Scheib <[email protected]> Added missing pointers to release notes (ansible#14659) * Replaced with larger graphic. * Revert "Replaced with larger graphic." This reverts commit 1214b00. * Added missing pointers to release notes. Make vault init more idempotent (ansible#14664) Currently if you cleanup docker volume for vault and bring docker-compose development back up with vault enabled we will not initialize vault because the secret files still exist. This change will attempt to initialize vault reguardless and update the secret file if vault is initialized Remove unused methods we attach to user model (ansible#14668) Update RBAC docs, remove unused get_permissions (ansible#14492) * Update RBAC docs, remove unused get_permissions * Add back in section for get_roles_on_resource Upgrade doc requirements (ansible#14669) * upgrade when pip compiling doc reqs * upgrade doc requirements allow pytest --migrations to succeed (ansible#14663) * allow pytest --migrations to succeed * We actually subvert migrations from running in test via pytest.ini --no-migrations option. This has led to bit rot for the sqlite migrations happy path. This changeset pays off that tech debt and allows for an sqlite migration happy path. * This paves the way for programatic invocation of individual migrations and weaving of the creation of resources (i.e. Instance, Job Template, etc). With this, a developer can instantiate various database states, trigger a migration, assert the state of the db, and then have pytest rollback all of that. * I will note that in practice, running these migrations is dog shit slow BUT this work also opens up the possibility of saving and re-using sqlite3 database files. Normally, caching is not THE answer and causes more harm than good. But in this case, our migrations are mostly write-once (I say mostly because this change set violates that :) so cache invalidation isn't a major issue. * functional test for migrations on sqlite * We commonly subvert running migrations in test land. Test land uses sqlite. By not constantly exercising this code path it atrophies. The smoke test here is to continuously exercise that code path. * Add ci test to run migration tests separately, they take =~ 2-3 minutes each on my laptop. * The smoke tests also serves as an example of how to write migration tests. * run migration tests in ci Fix awx collection publishing on galaxy (ansible#14642) --location (-L) parameter will prompt curl to submit a new request if the URL is a redirect. After moving to galaxy-NG without -L the curl falsely return 302 for any version Co-authored-by: John Barker <[email protected]> Fixing wsrelay connection loop (ansible#14692) * Fixing wsrelay connection loop * The loop was being interrupted when reaching the return statements, causing a race condition that would make nodes remain disconnected from their websockets * Added log messages for the previous return state to improve the logging from this state. * Added logging for malformed payload * Update awx/main/wsrelay.py Co-authored-by: Rick Elrod <[email protected]> * Moved logmsg outside condition --------- Co-authored-by: Lucas Benedito <[email protected]> Co-authored-by: Rick Elrod <[email protected]> Fix the bulk Job Launch Integration test in awx collection (ansible#14702) * fix the integration tests [CI] Reduce GHA timeouts from 6h default (ansible#14704) * [CI] Reduce GHA timeouts from 6h default The goal here is to never interfere with a real run (so most of the timeout-minutes values seem rather high) but to avoid having 6h long runs if something goes crazy and never ends. Signed-off-by: Rick Elrod <[email protected]> * Do bash hackery instead Signed-off-by: Rick Elrod <[email protected]> --------- Signed-off-by: Rick Elrod <[email protected]> separate tox calls in readthedocs config (ansible#14673) Add TLS certificate auth for HashiCorp Vault (ansible#14534) * Add TLS certificate auth for HashiCorp Vault Add support for AWX to authenticate with HashiCorp Vault using TLS client certificates. Also updates the documentation for the HashiCorp Vault secret management plugins to include both the new TLS options and the missing Kubernetes auth method options. Signed-off-by: Andrew Austin <[email protected]> * Refactor docker-compose vault for TLS cert auth Add TLS configuration to the docker-compose Vault configuration and use that method by default in vault plumbing. This ensures that the result of bringing up the docker-compose stack with vault enabled and running the plumb-vault playbook is a fully working credential retrieval setup using TLS client cert authentication. Signed-off-by: Andrew Austin <[email protected]> * Remove incorrect trailing space Co-authored-by: Hao Liu <[email protected]> * Make vault init idempotent - improve error handling for vault_initialization - ignore error if vault cert auth is already configured - removed unused register * Add VAULT_TLS option Make TLS for HashiCorp Vault optional and configurable via VAULT_TLS env var * Add retries for vault init Sometime it took longer for vault to fully come up and init will fail --------- Signed-off-by: Andrew Austin <[email protected]> Co-authored-by: Hao Liu <[email protected]> Co-authored-by: Hao Liu <[email protected]> remove unnecessary required flags for saml backend (ansible#14666) Signed-off-by: Tyler Muir <[email protected]> Dependabot for docsite requirements (ansible#14670) Add django-ansible-base (ansible#14705) * add django-ansible-base Signed-off-by: jessicamack <[email protected]> * add licenses * add django-ansible-base Signed-off-by: jessicamack <[email protected]> * add licenses * apply patch to fix permissions issue --------- Signed-off-by: jessicamack <[email protected]> Remove incorrectly formatted line from requirements.txt (ansible#14714) remove git+ line Fix updater bug due to missing newline at EOF (ansible#14713) Fix undefined error in settings/logging/edit form (ansible#14715) Fix undefined error in logging settings edit form Update setuptools-scm (ansible#14716) * properly format requirement * upgrade setuptools_scm * Revert "properly format requirement" This reverts commit 4c87929. * test ansible-runner package upgrade * Revert "test ansible-runner package upgrade" This reverts commit ba4b74f. Adding hosts bulk deletion feature (ansible#14462) * Adding hosts bulk deletion feature Signed-off-by: Avi Layani <[email protected]> * fix the type of the argument Signed-off-by: Avi Layani <[email protected]> * fixing activity_entry tracking Signed-off-by: Avi Layani <[email protected]> * Revert "fixing activity_entry tracking" This reverts commit c8eab52. Since the bulk_delete is not related to an inventory, only hosts which can be from different inventories. * get only needed vars to reduce memory consumption Signed-off-by: Avi Layani <[email protected]> * filtering the data to reduce memory increase the number of queries Signed-off-by: Avi Layani <[email protected]> * update the activity stream for inventories Signed-off-by: Avi Layani <[email protected]> * fix the changes dict initialiazation Signed-off-by: Avi Layani <[email protected]> --------- Signed-off-by: Avi Layani <[email protected]> Remove superwatcher from docker-compose dev (ansible#14708) When making changes to the application sometime you can accidentally cause FATAL state and cause the dev container to crash which will remove any ephemeral changes that you have made and is ANNOYING! Recover rsyslog from 4xx error Due to ansible#7560 'omhttp' module for rsyslog will completely stop forwarding message to external log aggregator after receiving a 4xx error from the external log aggregator This PR is an "workaround" for this problem by restarting rsyslogd after detecting that rsyslog received a 4xx error Correct misuse of stdxxx_event_enabled Not every log messages need to be emitted as a event! Send SIGKILL to rsyslog if hard cancellation is needed Simplify RBAC get_roles_on_resource method (ansible#14710) * Simplify RBAC get_roles_on_resource method * Fix bug * Fix query type bug Narrow the actor types accepted for RBAC evaluations (ansible#14709) * Narrow the scope of RBAC evaluations * Update tests for RBAC method changes * Simplify querset for credentials in org * Fix call pattern to pass in team role obj Use filtering/sorting from django-ansible-base (ansible#14726) * Move filtering to DAB * add comment to trigger building a new image Signed-off-by: jessicamack <[email protected]> * remove unneeded comment Signed-off-by: jessicamack <[email protected]> * remove unused imports Signed-off-by: jessicamack <[email protected]> * change mock import Signed-off-by: jessicamack <[email protected]> --------- Signed-off-by: jessicamack <[email protected]> Co-authored-by: jessicamack <[email protected]> add awx collection export tests * Basic export tests * Added test that highlights a problem with running Schedule exports as non-root user. We rely on the POST key in the OPTIONS response to determine the fields to export for a resource. The POST key is not present if a user does NOT have create privileges. * Fixed up forwarding all headers from the API server back to the test code. This was causing a problem in awxkit code that checks for allowed HTTP Verbs in the headers. refactor awxkit import code * Move awxkit import code into a pytest fixture to better control when the import happens * Ensure /awx_devel/awxkit is added to sys path before awxkit import runs Fix twilio_backend.py to send SMS to multiple destinations. (ansible#14656) AWX only sends Twilio notifications to one destination with the current version of code, but this is a bug. Fixed this bug for sending SMS to multiple destinations. Persist schedule prompt on launch fields when editing (ansible#14736) * persist schedule prompt on launch fields when editing * Merge job template default credentials with schedule overrides in schedule prompt * rename vars for clarity * handle undefined defaultCredentials --------- Co-authored-by: Michael Abashian <[email protected]>

github-actions bot added component:docs community labels Oct 26, 2023

oraNod requested review from AlanCoding, tvo318, thedoubl3j and TheRealHaoLiu October 26, 2023 15:44

oraNod changed the title ~~Api reference~~ Docs: Include REST API reference content from swagger.json Oct 26, 2023

tvo318 approved these changes Nov 1, 2023

View reviewed changes

oraNod added 4 commits November 3, 2023 11:27

set up rest api docs

d0aa405

download the swagger json file

f41658e

add download to tox docs build

7bf29ec

use community-docs folder

b02d682

oraNod force-pushed the api-reference branch from e3be1a1 to b02d682 Compare November 3, 2023 11:27

Merge branch 'devel' into api-reference

20ce84f

fosterseth reviewed Nov 10, 2023

View reviewed changes

TheRealHaoLiu merged commit 0057c8d into ansible:devel Nov 11, 2023
20 checks passed

oraNod mentioned this pull request Nov 16, 2023

[DOCS] AWX site tab misses icon #14591

Closed

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Include REST API reference content from swagger.json #14607

Docs: Include REST API reference content from swagger.json #14607

oraNod commented Oct 26, 2023

oraNod commented Oct 26, 2023

oraNod commented Oct 26, 2023 •

edited

Loading

tvo318 left a comment

oraNod commented Nov 3, 2023

fosterseth Nov 10, 2023

oraNod Nov 15, 2023

fosterseth commented Nov 10, 2023

oraNod commented Nov 15, 2023

oraNod commented Nov 15, 2023

Docs: Include REST API reference content from swagger.json #14607

Docs: Include REST API reference content from swagger.json #14607

Conversation

oraNod commented Oct 26, 2023

SUMMARY

ISSUE TYPE

COMPONENT NAME

AWX VERSION

ADDITIONAL INFORMATION

oraNod commented Oct 26, 2023

oraNod commented Oct 26, 2023 • edited Loading

tvo318 left a comment

Choose a reason for hiding this comment

oraNod commented Nov 3, 2023

fosterseth Nov 10, 2023

Choose a reason for hiding this comment

oraNod Nov 15, 2023

Choose a reason for hiding this comment

fosterseth commented Nov 10, 2023

oraNod commented Nov 15, 2023

oraNod commented Nov 15, 2023

oraNod commented Oct 26, 2023 •

edited

Loading