Skip to content

Use rswag to update openapi spec#2085

Open
sanason wants to merge 4 commits into
mainfrom
add-swagger-api-docs
Open

Use rswag to update openapi spec#2085
sanason wants to merge 4 commits into
mainfrom
add-swagger-api-docs

Conversation

@sanason

@sanason sanason commented Jun 24, 2026

Copy link
Copy Markdown
Member

The purpose of this PR is to update the OpenAPI spec for the V1 Touchpoints API. The updated spec adds documentation for the following endpoints:

  • /forms/{id}/responses
  • /service_providers
  • /services
  • /services/{id}
  • /cx_collection_details
  • /cx_collections
  • /cx_responses

It removes documentation for two digital registry endpoints:

  • /digital_products
  • /digital_service_accounts

Those endpoints still exist but, since the public-facing digital registry was shuttered in 2024, I'm not willing to maintain the documentation for the corresponding API endpoints. /websites is still documented because I know that GSA is still using the website registry as its internal inventory tool.

@sanason sanason linked an issue Jun 24, 2026 that may be closed by this pull request
Comment thread spec/factories/cx_collection_detail_upload.rb Dismissed
Comment thread spec/factories/cx_collection_detail_upload.rb Dismissed
Comment thread spec/factories/cx_collection_detail_upload.rb Dismissed
Comment thread spec/factories/cx_collection_detail_upload.rb Dismissed
@@ -1,19 +0,0 @@
# frozen_string_literal: true

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Safe to delete - no routes are mapped to this controller.

@@ -27,6 +27,7 @@ def index
meta: {
current_page: cx_responses.current_page,
size: cx_responses.size,

@sanason sanason Jun 26, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding this here so it matches the meta block in /forms/{id}/responses.

if current_user.organizational_admin?
render json: current_user.organization.forms
.order(:id)
.limit(100), each_serializer: FormSerializer

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like this undocumented and arbitrary limit. A safer solution would be to add pagination but the API already has a bunch of unlimited endpoints and I don't think this one is more of a risk than any of them.

Comment thread config/routes.rb
end
namespace :v1 do
resources :organizations, only: [:index]
resources :collections, only: [:index]

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deleting because this route has no corresponding controller.

@@ -54,8 +54,8 @@
expect(csv.class).to eq(CSV::Table)
expect(csv.size).to eq(2)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed because the factory changed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve Touchpoints API documentation

2 participants