search

pact-foundation / pact_broker

Enables your consumer driven contracts workflow
http://pactflow.io
MIT License
702 stars 173 forks source link

Create Swagger documentation #89

Open mefellows opened 7 years ago

mefellows commented 7 years ago

Whilst the wiki does have information and there is a HAL browser, it would be ideal to have the API published in a format such as Swagger. This request has come up a few times on various forums.

I personally find the HAL browser quite confusing from a (human) usability perspective and seemingly I'm not alone.

Thoughts?

bethesque commented 7 years ago

Yup, good idea.

YOU54F commented 5 years ago

Hey,

Just to let you know, I had a quick look into this as I really like swagger and advocate it's use alot in API design.

As you already have a full service in place, it may be worth leveraging some tools in ruby that can generate swagger documentation. That way, you can ensure the documentation stays up to date as you make changes to the application, without having to worry about having to tend to the boring job of documenting the API and more time on other things.

There are some existing tools out there but most seem to be around rails

Name Description
grape-swagger Add Swagger compliant documentation to your grape API.
swagger-blocks Define and serve live-updating Swagger JSON for Ruby apps.
rspec-rails-swagger Generate Swagger 2.0 docs for Rails apps using RSpec request specs. Test results can be captured as response examples.
rswag Swagger tooling for Rails API's. Generate beautiful API documentation, including a UI to explore and test operations, directly from your rspec integration tests.

I was trying to understand the architecture of the project. as I am unfamiliar with the ruby ecosystem.

If I am correct, you used to use Sinatra but now you use Webmachine-ruby for sending HTTP requests.

Rake is your middleware?

Noob question. This isn't a rails or ruby on rails project? Is that just all the things packaged for you in a nice box?

the rspec tools look interesting, as it looks like you use rspec, but was unsure as they all seem to be for rails projects, and I didn't know if looking down those routes would be a dead end.

Doing some experimentation on a fork and if I get anywhere I'll post back :)

bethesque commented 5 years ago

Swagger documentation would be awesome! I'd be really happy to have your help on this, as I once tried to give it a go by hand, and just got overwhelmed by how much there was to do.

If I am correct, you used to use Sinatra but now you use Webmachine-ruby for sending HTTP requests.

The API is a Webmachine application (not Sinatra - that's the UI). There is no Rails in this project. Yes, it uses Rack as the middleware framework. The R in RSpec is for ruby, not rails.

Here are some docs about how the project is structured: https://github.com/pact-foundation/pact_broker/blob/master/DEVELOPER_DOCUMENTATION.md

The routes are defined here: https://github.com/pact-foundation/pact_broker/blob/master/lib/pact_broker/api.rb

You'll find the API code here: https://github.com/pact-foundation/pact_broker/tree/master/lib/pact_broker/api

The decorators (the classes that render the JSON responses) are here: https://github.com/pact-foundation/pact_broker/tree/master/lib/pact_broker/api/decorators

If you have any questions, let me know!

jaecktec commented 3 years ago

My search in finding anything that can be just 'plugged in' for Webmachine the Rack adapter was not successful, so I guess there is nothing but writing out every json response in some sort of dsl?

bethesque commented 3 years ago

I've been mulling a little bit about how we could automate this. I wrote some code to create a "rake routes" like task, and I think we could extend it to automatically generate an example of the response body for each route at the least. A while ago I went looking for a tool that would reverse engineer a swagger schema document from examples, but I didn't manage to find one. If something like that exists now, it would be a good start.

YOU54F commented 2 years ago

So @bethesque

I took a look at the code you wrote here to describe the routes.

They are run and printed out as part of the rake task.

https://github.com/pact-foundation/pact_broker/blob/91452db76d3888c69941b24a8162baceee943cb4/tasks/development.rake#L44

I updated it so it would output an array of paths

Screenshot 2022-04-19 at 22 25 06

mapped the output to an OAS handlebars template

const handlebars = require('handlebars')
const data = require('./routes.json')
const template = `openapi: '3.0.3'

info:
  version: "0.0.1"
  title: "pact test"

paths:
{{#each this}}
  {{this.path}}:
    get:
      summary: {{this.class}}
      operationId: {{this.path}}
      responses:
        default:
          description: {{this.class}}
{{/each}}
`
const render = handlebars.compile(template, { noEscape: true })
const res = render(data, {helpers: { json: JSON.stringify }})
console.log(res)

Which has given me this beast. Obviously missing a load of stuff, but cool for a starter for 10.

openapi: '3.0.3'

info:
  version: "0.0.1"
  title: "pact test"

paths:
  /:
    get:
      summary: PactBroker::Api::Resources::Index
      operationId: /
      responses:
        default:
          description: PactBroker::Api::Resources::Index
  /can-i-deploy:
    get:
      summary: PactBroker::Api::Resources::CanIDeploy
      operationId: /can-i-deploy
      responses:
        default:
          description: PactBroker::Api::Resources::CanIDeploy
  /contracts/publish:
    get:
      summary: PactBroker::Api::Resources::PublishContracts
      operationId: /contracts/publish
      responses:
        default:
          description: PactBroker::Api::Resources::PublishContracts
  /dashboard:
    get:
      summary: PactBroker::Api::Resources::Dashboard
      operationId: /dashboard
      responses:
        default:
          description: PactBroker::Api::Resources::Dashboard
  /dashboard/provider/:provider_name/consumer/:consumer_name:
    get:
      summary: PactBroker::Api::Resources::Dashboard
      operationId: /dashboard/provider/:provider_name/consumer/:consumer_name
      responses:
        default:
          description: PactBroker::Api::Resources::Dashboard
  /deployed-versions/:uuid:
    get:
      summary: PactBroker::Api::Resources::DeployedVersion
      operationId: /deployed-versions/:uuid
      responses:
        default:
          description: PactBroker::Api::Resources::DeployedVersion
  /environments:
    get:
      summary: PactBroker::Api::Resources::Environments
      operationId: /environments
      responses:
        default:
          description: PactBroker::Api::Resources::Environments
  /environments/:environment_uuid:
    get:
      summary: PactBroker::Api::Resources::Environment
      operationId: /environments/:environment_uuid
      responses:
        default:
          description: PactBroker::Api::Resources::Environment
  /environments/:environment_uuid/deployed-versions/currently-deployed:
    get:
      summary: PactBroker::Api::Resources::CurrentlyDeployedVersionsForEnvironment
      operationId: /environments/:environment_uuid/deployed-versions/currently-deployed
      responses:
        default:
          description: PactBroker::Api::Resources::CurrentlyDeployedVersionsForEnvironment
  /environments/:environment_uuid/released-versions/currently-supported:
    get:
      summary: PactBroker::Api::Resources::CurrentlySupportedVersionsForEnvironment
      operationId: /environments/:environment_uuid/released-versions/currently-supported
      responses:
        default:
          description: PactBroker::Api::Resources::CurrentlySupportedVersionsForEnvironment
  /groups/:pacticipant_name:
    get:
      summary: PactBroker::Api::Resources::Group
      operationId: /groups/:pacticipant_name
      responses:
        default:
          description: PactBroker::Api::Resources::Group
  /integrations:
    get:
      summary: PactBroker::Api::Resources::Integrations
      operationId: /integrations
      responses:
        default:
          description: PactBroker::Api::Resources::Integrations
  /integrations/provider/:provider_name/consumer/:consumer_name:
    get:
      summary: PactBroker::Api::Resources::Integration
      operationId: /integrations/provider/:provider_name/consumer/:consumer_name
      responses:
        default:
          description: PactBroker::Api::Resources::Integration
  /matrix:
    get:
      summary: PactBroker::Api::Resources::Matrix
      operationId: /matrix
      responses:
        default:
          description: PactBroker::Api::Resources::Matrix
  /matrix/provider/:provider_name/consumer/:consumer_name:
    get:
      summary: PactBroker::Api::Resources::MatrixForConsumerAndProvider
      operationId: /matrix/provider/:provider_name/consumer/:consumer_name
      responses:
        default:
          description: PactBroker::Api::Resources::MatrixForConsumerAndProvider
  /matrix/provider/:provider_name/latest/:provider_tag/consumer/:consumer_name/latest/:tag/badge:
    get:
      summary: PactBroker::Api::Resources::MatrixBadge
      operationId: /matrix/provider/:provider_name/latest/:provider_tag/consumer/:consumer_name/latest/:tag/badge
      responses:
        default:
          description: PactBroker::Api::Resources::MatrixBadge
  /metrics:
    get:
      summary: PactBroker::Api::Resources::Metrics
      operationId: /metrics
      responses:
        default:
          description: PactBroker::Api::Resources::Metrics
  /pact/provider/:provider_name/consumer/:consumer_name/latest:
    get:
      summary: PactBroker::Api::Resources::LatestPact
      operationId: /pact/provider/:provider_name/consumer/:consumer_name/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestPact
  /pact/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number:
    get:
      summary: PactBroker::Api::Resources::Pact
      operationId: /pact/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number
      responses:
        default:
          description: PactBroker::Api::Resources::Pact
  /pacticipants:
    get:
      summary: PactBroker::Api::Resources::Pacticipants
      operationId: /pacticipants
      responses:
        default:
          description: PactBroker::Api::Resources::Pacticipants
  /pacticipants/:pacticipant_name:
    get:
      summary: PactBroker::Api::Resources::Pacticipant
      operationId: /pacticipants/:pacticipant_name
      responses:
        default:
          description: PactBroker::Api::Resources::Pacticipant
  /pacticipants/:pacticipant_name/branches/:branch_name/latest-version/can-i-deploy/to-environment/:environment_name:
    get:
      summary: PactBroker::Api::Resources::CanIDeployPacticipantVersionByBranchToEnvironment
      operationId: /pacticipants/:pacticipant_name/branches/:branch_name/latest-version/can-i-deploy/to-environment/:environment_name
      responses:
        default:
          description: PactBroker::Api::Resources::CanIDeployPacticipantVersionByBranchToEnvironment
  /pacticipants/:pacticipant_name/branches/:branch_name/latest-version/can-i-deploy/to-environment/:environment_name/badge:
    get:
      summary: PactBroker::Api::Resources::CanIDeployPacticipantVersionByBranchToEnvironmentBadge
      operationId: /pacticipants/:pacticipant_name/branches/:branch_name/latest-version/can-i-deploy/to-environment/:environment_name/badge
      responses:
        default:
          description: PactBroker::Api::Resources::CanIDeployPacticipantVersionByBranchToEnvironmentBadge
  /pacticipants/:pacticipant_name/branches/:branch_name/versions/:version_number:
    get:
      summary: PactBroker::Api::Resources::BranchVersion
      operationId: /pacticipants/:pacticipant_name/branches/:branch_name/versions/:version_number
      responses:
        default:
          description: PactBroker::Api::Resources::BranchVersion
  /pacticipants/:pacticipant_name/labels/:label_name:
    get:
      summary: PactBroker::Api::Resources::Label
      operationId: /pacticipants/:pacticipant_name/labels/:label_name
      responses:
        default:
          description: PactBroker::Api::Resources::Label
  /pacticipants/:pacticipant_name/latest-version:
    get:
      summary: PactBroker::Api::Resources::LatestVersion
      operationId: /pacticipants/:pacticipant_name/latest-version
      responses:
        default:
          description: PactBroker::Api::Resources::LatestVersion
  /pacticipants/:pacticipant_name/latest-version/:tag:
    get:
      summary: PactBroker::Api::Resources::LatestVersion
      operationId: /pacticipants/:pacticipant_name/latest-version/:tag
      responses:
        default:
          description: PactBroker::Api::Resources::LatestVersion
  /pacticipants/:pacticipant_name/latest-version/:tag/can-i-deploy/to/:to:
    get:
      summary: PactBroker::Api::Resources::CanIDeployPacticipantVersionByTagToTag
      operationId: /pacticipants/:pacticipant_name/latest-version/:tag/can-i-deploy/to/:to
      responses:
        default:
          description: PactBroker::Api::Resources::CanIDeployPacticipantVersionByTagToTag
  /pacticipants/:pacticipant_name/latest-version/:tag/can-i-deploy/to/:to/badge:
    get:
      summary: PactBroker::Api::Resources::CanIDeployPacticipantVersionByTagToTagBadge
      operationId: /pacticipants/:pacticipant_name/latest-version/:tag/can-i-deploy/to/:to/badge
      responses:
        default:
          description: PactBroker::Api::Resources::CanIDeployPacticipantVersionByTagToTagBadge
  /pacticipants/:pacticipant_name/versions:
    get:
      summary: PactBroker::Api::Resources::Versions
      operationId: /pacticipants/:pacticipant_name/versions
      responses:
        default:
          description: PactBroker::Api::Resources::Versions
  /pacticipants/:pacticipant_name/versions/:pacticipant_version_number:
    get:
      summary: PactBroker::Api::Resources::Version
      operationId: /pacticipants/:pacticipant_name/versions/:pacticipant_version_number
      responses:
        default:
          description: PactBroker::Api::Resources::Version
  /pacticipants/:pacticipant_name/versions/:pacticipant_version_number/deployed-versions/environment/:environment_uuid:
    get:
      summary: PactBroker::Api::Resources::DeployedVersionsForVersionAndEnvironment
      operationId: /pacticipants/:pacticipant_name/versions/:pacticipant_version_number/deployed-versions/environment/:environment_uuid
      responses:
        default:
          description: PactBroker::Api::Resources::DeployedVersionsForVersionAndEnvironment
  /pacticipants/:pacticipant_name/versions/:pacticipant_version_number/released-versions/environment/:environment_uuid:
    get:
      summary: PactBroker::Api::Resources::ReleasedVersionsForVersionAndEnvironment
      operationId: /pacticipants/:pacticipant_name/versions/:pacticipant_version_number/released-versions/environment/:environment_uuid
      responses:
        default:
          description: PactBroker::Api::Resources::ReleasedVersionsForVersionAndEnvironment
  /pacticipants/:pacticipant_name/versions/:pacticipant_version_number/tags/:tag_name:
    get:
      summary: PactBroker::Api::Resources::Tag
      operationId: /pacticipants/:pacticipant_name/versions/:pacticipant_version_number/tags/:tag_name
      responses:
        default:
          description: PactBroker::Api::Resources::Tag
  /pacticipants/label/:label_name:
    get:
      summary: PactBroker::Api::Resources::PacticipantsForLabel
      operationId: /pacticipants/label/:label_name
      responses:
        default:
          description: PactBroker::Api::Resources::PacticipantsForLabel
  /pacts/latest:
    get:
      summary: PactBroker::Api::Resources::LatestPacts
      operationId: /pacts/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestPacts
  /pacts/provider/:provider_name:
    get:
      summary: PactBroker::Api::Resources::ProviderPacts
      operationId: /pacts/provider/:provider_name
      responses:
        default:
          description: PactBroker::Api::Resources::ProviderPacts
  /pacts/provider/:provider_name/consumer/:consumer_name/branch/:branch_name:
    get:
      summary: PactBroker::Api::Resources::PactVersionsForBranch
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/branch/:branch_name
      responses:
        default:
          description: PactBroker::Api::Resources::PactVersionsForBranch
  /pacts/provider/:provider_name/consumer/:consumer_name/latest:
    get:
      summary: PactBroker::Api::Resources::LatestPact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestPact
  /pacts/provider/:provider_name/consumer/:consumer_name/latest-untagged:
    get:
      summary: PactBroker::Api::Resources::LatestPact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest-untagged
      responses:
        default:
          description: PactBroker::Api::Resources::LatestPact
  /pacts/provider/:provider_name/consumer/:consumer_name/latest-untagged/badge:
    get:
      summary: PactBroker::Api::Resources::Badge
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest-untagged/badge
      responses:
        default:
          description: PactBroker::Api::Resources::Badge
  /pacts/provider/:provider_name/consumer/:consumer_name/latest/:tag:
    get:
      summary: PactBroker::Api::Resources::LatestPact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest/:tag
      responses:
        default:
          description: PactBroker::Api::Resources::LatestPact
  /pacts/provider/:provider_name/consumer/:consumer_name/latest/:tag/badge:
    get:
      summary: PactBroker::Api::Resources::Badge
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest/:tag/badge
      responses:
        default:
          description: PactBroker::Api::Resources::Badge
  /pacts/provider/:provider_name/consumer/:consumer_name/latest/:tag/verification-results/latest:
    get:
      summary: PactBroker::Api::Resources::LatestVerificationForLatestPact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest/:tag/verification-results/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestVerificationForLatestPact
  /pacts/provider/:provider_name/consumer/:consumer_name/latest/badge:
    get:
      summary: PactBroker::Api::Resources::Badge
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest/badge
      responses:
        default:
          description: PactBroker::Api::Resources::Badge
  /pacts/provider/:provider_name/consumer/:consumer_name/latest/verification-results/latest:
    get:
      summary: PactBroker::Api::Resources::LatestVerificationForLatestPact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/latest/verification-results/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestVerificationForLatestPact
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha:
    get:
      summary: PactBroker::Api::Resources::PactVersion
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha
      responses:
        default:
          description: PactBroker::Api::Resources::PactVersion
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/diff/pact-version/:comparison_pact_version_sha:
    get:
      summary: PactBroker::Api::Resources::PactContentDiff
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/diff/pact-version/:comparison_pact_version_sha
      responses:
        default:
          description: PactBroker::Api::Resources::PactContentDiff
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/metadata/:metadata:
    get:
      summary: PactBroker::Api::Resources::PactVersion
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/metadata/:metadata
      responses:
        default:
          description: PactBroker::Api::Resources::PactVersion
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/metadata/:metadata/verification-results:
    get:
      summary: PactBroker::Api::Resources::Verifications
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/metadata/:metadata/verification-results
      responses:
        default:
          description: PactBroker::Api::Resources::Verifications
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/metadata/:metadata/verification-results/:verification_number:
    get:
      summary: PactBroker::Api::Resources::Verification
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/metadata/:metadata/verification-results/:verification_number
      responses:
        default:
          description: PactBroker::Api::Resources::Verification
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results:
    get:
      summary: PactBroker::Api::Resources::Verifications
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results
      responses:
        default:
          description: PactBroker::Api::Resources::Verifications
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results/:verification_number:
    get:
      summary: PactBroker::Api::Resources::Verification
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results/:verification_number
      responses:
        default:
          description: PactBroker::Api::Resources::Verification
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results/:verification_number/triggered-webhooks:
    get:
      summary: PactBroker::Api::Resources::VerificationTriggeredWebhooks
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results/:verification_number/triggered-webhooks
      responses:
        default:
          description: PactBroker::Api::Resources::VerificationTriggeredWebhooks
  /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results/latest:
    get:
      summary: PactBroker::Api::Resources::LatestVerificationForPact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/pact-version/:pact_version_sha/verification-results/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestVerificationForPact
  /pacts/provider/:provider_name/consumer/:consumer_name/tag/:tag:
    get:
      summary: PactBroker::Api::Resources::TaggedPactVersions
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/tag/:tag
      responses:
        default:
          description: PactBroker::Api::Resources::TaggedPactVersions
  /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number:
    get:
      summary: PactBroker::Api::Resources::Pact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number
      responses:
        default:
          description: PactBroker::Api::Resources::Pact
  /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/diff/previous-distinct:
    get:
      summary: PactBroker::Api::Resources::PactContentDiff
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/diff/previous-distinct
      responses:
        default:
          description: PactBroker::Api::Resources::PactContentDiff
  /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/diff/version/:comparison_consumer_version:
    get:
      summary: PactBroker::Api::Resources::PactContentDiff
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/diff/version/:comparison_consumer_version
      responses:
        default:
          description: PactBroker::Api::Resources::PactContentDiff
  /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/previous-distinct:
    get:
      summary: PactBroker::Api::Resources::PreviousDistinctPactVersion
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/previous-distinct
      responses:
        default:
          description: PactBroker::Api::Resources::PreviousDistinctPactVersion
  /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/triggered-webhooks:
    get:
      summary: PactBroker::Api::Resources::PactTriggeredWebhooks
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/triggered-webhooks
      responses:
        default:
          description: PactBroker::Api::Resources::PactTriggeredWebhooks
  /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/verification-results/latest:
    get:
      summary: PactBroker::Api::Resources::LatestVerificationForPact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/version/:consumer_version_number/verification-results/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestVerificationForPact
  /pacts/provider/:provider_name/consumer/:consumer_name/versions:
    get:
      summary: PactBroker::Api::Resources::PactVersions
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/versions
      responses:
        default:
          description: PactBroker::Api::Resources::PactVersions
  /pacts/provider/:provider_name/consumer/:consumer_name/versions/:consumer_version_number:
    get:
      summary: PactBroker::Api::Resources::Pact
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/versions/:consumer_version_number
      responses:
        default:
          description: PactBroker::Api::Resources::Pact
  /pacts/provider/:provider_name/consumer/:consumer_name/webhooks:
    get:
      summary: PactBroker::Api::Resources::PactWebhooks
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/webhooks
      responses:
        default:
          description: PactBroker::Api::Resources::PactWebhooks
  /pacts/provider/:provider_name/consumer/:consumer_name/webhooks/status:
    get:
      summary: PactBroker::Api::Resources::PactWebhooksStatus
      operationId: /pacts/provider/:provider_name/consumer/:consumer_name/webhooks/status
      responses:
        default:
          description: PactBroker::Api::Resources::PactWebhooksStatus
  /pacts/provider/:provider_name/for-verification:
    get:
      summary: PactBroker::Api::Resources::ProviderPactsForVerification
      operationId: /pacts/provider/:provider_name/for-verification
      responses:
        default:
          description: PactBroker::Api::Resources::ProviderPactsForVerification
  /pacts/provider/:provider_name/latest:
    get:
      summary: PactBroker::Api::Resources::LatestProviderPacts
      operationId: /pacts/provider/:provider_name/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestProviderPacts
  /pacts/provider/:provider_name/latest/:tag:
    get:
      summary: PactBroker::Api::Resources::LatestProviderPacts
      operationId: /pacts/provider/:provider_name/latest/:tag
      responses:
        default:
          description: PactBroker::Api::Resources::LatestProviderPacts
  /pacts/provider/:provider_name/tag/:tag:
    get:
      summary: PactBroker::Api::Resources::ProviderPacts
      operationId: /pacts/provider/:provider_name/tag/:tag
      responses:
        default:
          description: PactBroker::Api::Resources::ProviderPacts
  /relationships:
    get:
      summary: PactBroker::Api::Resources::Relationships
      operationId: /relationships
      responses:
        default:
          description: PactBroker::Api::Resources::Relationships
  /released-versions/:uuid:
    get:
      summary: PactBroker::Api::Resources::ReleasedVersion
      operationId: /released-versions/:uuid
      responses:
        default:
          description: PactBroker::Api::Resources::ReleasedVersion
  /test/error:
    get:
      summary: PactBroker::Api::Resources::ErrorTest
      operationId: /test/error
      responses:
        default:
          description: PactBroker::Api::Resources::ErrorTest
  /trace/:*:
    get:
      summary: Webmachine::Trace::TraceResource
      operationId: /trace/:*
      responses:
        default:
          description: Webmachine::Trace::TraceResource
  /triggered-webhooks/:uuid/logs:
    get:
      summary: PactBroker::Api::Resources::TriggeredWebhookLogs
      operationId: /triggered-webhooks/:uuid/logs
      responses:
        default:
          description: PactBroker::Api::Resources::TriggeredWebhookLogs
  /verification-results/consumer/:consumer_name/version/:consumer_version_number/latest:
    get:
      summary: PactBroker::Api::Resources::LatestVerificationsForConsumerVersion
      operationId: /verification-results/consumer/:consumer_name/version/:consumer_version_number/latest
      responses:
        default:
          description: PactBroker::Api::Resources::LatestVerificationsForConsumerVersion
  /webhooks:
    get:
      summary: PactBroker::Api::Resources::AllWebhooks
      operationId: /webhooks
      responses:
        default:
          description: PactBroker::Api::Resources::AllWebhooks
  /webhooks/:uuid:
    get:
      summary: PactBroker::Api::Resources::Webhook
      operationId: /webhooks/:uuid
      responses:
        default:
          description: PactBroker::Api::Resources::Webhook
  /webhooks/:uuid/execute:
    get:
      summary: PactBroker::Api::Resources::WebhookExecution
      operationId: /webhooks/:uuid/execute
      responses:
        default:
          description: PactBroker::Api::Resources::WebhookExecution
  /webhooks/consumer/:consumer_name:
    get:
      summary: PactBroker::Api::Resources::PacticipantWebhooks
      operationId: /webhooks/consumer/:consumer_name
      responses:
        default:
          description: PactBroker::Api::Resources::PacticipantWebhooks
  /webhooks/execute:
    get:
      summary: PactBroker::Api::Resources::WebhookExecution
      operationId: /webhooks/execute
      responses:
        default:
          description: PactBroker::Api::Resources::WebhookExecution
  /webhooks/provider/:provider_name:
    get:
      summary: PactBroker::Api::Resources::PacticipantWebhooks
      operationId: /webhooks/provider/:provider_name
      responses:
        default:
          description: PactBroker::Api::Resources::PacticipantWebhooks
  /webhooks/provider/:provider_name/consumer/:consumer_name:
    get:
      summary: PactBroker::Api::Resources::PacticipantWebhooks
      operationId: /webhooks/provider/:provider_name/consumer/:consumer_name
      responses:
        default:
          description: PactBroker::Api::Resources::PacticipantWebhooks

The other thing I was thinking, inspired by our Postman example, where we document the application with a Postman collection, test it, and generate the OAS spec that way?

YOU54F commented 2 years ago

It's gonna be a beast of a spec file when it's complete

Screenshot 2022-04-19 at 22 31 33

YOU54F commented 2 years ago

I've been mulling a little bit about how we could automate this. I wrote some code to create a "rake routes" like task, and I think we could extend it to automatically generate an example of the response body for each route at the least. A while ago I went looking for a tool that would reverse engineer a swagger schema document from examples, but I didn't manage to find one. If something like that exists now, it would be a good start.

I think mapping the fields across to a template from the examples is a pretty decent way to get something quick, and repeatable.

not seen anyway swagger tools to generate from examples yet, I did have a play with this, as it looks promising, they have a Rack example

https://github.com/k0kubun/rspec-openapi

they have an rspec rake example

https://github.com/k0kubun/rspec-openapi/blob/master/spec/rspec/rack_test_spec.rb

which uses this spec helper file

https://github.com/k0kubun/rspec-openapi/blob/master/spec/spec_helper.rb

I tried plugging it in yesterday into the broker, but no bueno, need to dig a little deeper.