Frontmatter api prop compression is nondeterministic

[TheCatLady]

Describe the bug

On each gen-api-docs run, the frontmatter api prop changes.

Expected behavior

The frontmatter api prop has consistent output for a given input.

Current behavior

See someengineering/resoto.com#939, a pull request created by CI. There were no changes to the API spec.

Possible solution

Use a deterministic algorithm for compression.

Steps to reproduce

1. Generate API docs from the following specs: https://github.com/someengineering/resoto.com/tree/main/openapi
2. Regenerate and notice changed frontmatter.

Context

This issue makes it difficult to review pull requests, as actual changes to the API spec/docs are difficult to find within all of the frontmatter changes.

Your Environment

• Version used: 3.0.0-beta.4
• Link to your project: https://github.com/someengineering/resoto.com

[sserrata]

Hi @TheCatLady, thanks for reporting, I can see how this is indeed an issue. We don't see it on pan.dev because we chose not to check-in generated files. I'll investigate to see if there's a way to make compression deterministic or explore adding the option to disable/enable compression.

[sserrata]

Hi @TheCatLady , sorry for overdue follow up on this...after digging in, it appears the difference may be due to difference in OS between local development machine and CI. That said, I'm looking to add a disableCompression plugin option to let users override the default behavior.

[TheCatLady]

Hi @sserrata! Thanks so much for looking into this. I'm not sure if it's (only) a matter of difference in OS, as generating API docs multiple times from my local dev environment results in different outputs on some API routes.

Here's the API spec: https://github.com/someengineering/inventory.fix.security/blob/main/openapi/fixcore-edge.yml

[sserrata]

I've not been able to reproduce so far. Do you know exactly which endpoints are affected? Any chance they could be loading some external markdown/refs?

[TheCatLady]

I've not been able to reproduce so far. Do you know exactly which endpoints are affected? Any chance they could be loading some external markdown/refs?

Hi @sserrata, it appears to be the following endpoint:

  /timeseries/{timeseries}:
    post:
      summary: Load time series data.
      parameters:
        - name: timeseries
          description: 'The name of the time series.'
          in: path
          required: true
          schema:
            type: string
            example: 'some_name'
      requestBody:
        description: Parameters of the time series request.
        content:
          application/json:
            schema:
              type: object
              properties:
                start:
                  type: string
                  format: date-time
                  description: The start of the time series. If not defined 7 days from now into the past.
                end:
                  type: string
                  format: date-time
                  description: The end of the time series. If not defined now.
                group:
                  type: array
                  items:
                    type: string
                  description: Reduce the available groups to the set of defined ones.
                filter:
                  type: array
                  items:
                    type: string
                  description: |
                    Filter available group members by predicate.
                    Only time series values with matching group criteria will be selected.
                  example: group_var_foo == "bla"
                granularity:
                  type: string
                  format: duration
                  description: |
                    The granularity of the time series.
                    This can be either a duration or the number of items for the time window that is selected.
                    The granularity can not go below one hour.
                    It defaults to (end-start) / 20.
      tags:
        - timeseries
      responses:
        '400':
          description: 'A required property is missing or the request can not be read.'
          content:
            text/plain:
              schema:
                type: string
        default:
          description: The time series data
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example: |
                {
                  "time": "2021-01-01T00:00:00Z",
                  "value": 1
                }

[sserrata]

As mentioned in #819 adding an example or examples to the date-time properties should prevent the autogenerated value from appearing.