[api docs] increase schema validation strictness and start to fix issues

[jbylina]

Hi,

Thanks all the great work you're doing here!! This is my first ever PR in this repo, so I will appreciate any extra guidance :)

I would like to improve the OpenAPI docs so that I can use them to generate an odk API client. Today's docs/api.yaml doesn't comply with OpenAPI Specification v3.0.1 (as indicated in the first lines of the file). This seems to be a legacy of swagger-based api spec. #1593 introduces a great OpenAPI spec linter, starting with a minimal ruleset. This PR aims to upgrade the ruleset to recommended, and slowly decrease the number of linting errors. On this PR, redocly reports: 443 problems. I was able to get it down to 164 problems, which are mostly security-defined errors across all paths, but proposing such huge PR would be a reviewers' nightmare, so I would like to propose changes one by one.

This PR introduces 3 api docs changes:

1. Make HTTP statuses a strings to comply with: https://spec.openapis.org/oas/v3.0.1.html#fixed-fields-5 (responses -> Map[string, Response Object | Reference Object]) Eg. https://github.com/openapi-generators/openapi-python-client fails to open ODK spec due to this issue.
2. Add license node following LICENSE file
3. Add Individual Form description

What has been done to verify that this works as intended?

CI

Why is this the best possible solution? Were any other approaches considered?

It's an improvement of the already set solution.

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Updates artifact used by docs repo to render web docs. Initial change-set is minimal and shouldn't affect any user.

Does this change require updates to the API documentation? If so, please update docs/api.yaml as part of this PR.

It's a sole change to docs.

Before submitting this PR, please make sure you have:

• run make test and confirmed all checks still pass OR confirm CircleCI build passes
• verified that any code from external sources are properly credited in comments or that everything is internally sourced

[jbylina]

File created by (cd docs && npx --no @redocly/cli lint --extends=recommended api.yaml --generate-ignore-file) call. Having this file checked into repo enforces stricter rules on other contributions while working on improving existing problems.

[alxndrsn]

proposing such huge PR would be a reviewers' nightmare, so I would like to propose changes one by one.

Thanks - I really appreciate this approach 🙏

I will try to do a more detailed review this week; for now some quick queries:

• is there a rule-based alternative to the exceptions file? So we could slowly introduce new rules rather than having a (very) long list of explicit exceptions from the full recommended ruleset?
• is the recommended ruleset the minimum required to be OpenAPI 3.0.1 spec compliant? I'd have guessed that was what minimal was for, but it sounds like that's not the case

mostly security-defined errors across all paths

I think this relates to getodk/central#1213

[alxndrsn]

is there a reason to change the dir here?

[jbylina]

redocly hardcodes .redocly.lint-ignore.yaml file location to be in $PWD. cd allowed me to store this file along api.yaml, but after your comment that skipping entire rules would be better than ignoring individual errors in the file, I don't need .redocly.lint-ignore.yaml file now

[alxndrsn]

👍 I think tracking individual rule-changes and the associated changes in docs/api.yaml will be eased by #1650, which defines the current config explicitly.

[jbylina]

Hey @alxndrsn, Thanks for the initial review.

is there a rule-based alternative to the exceptions file? So we could slowly introduce new rules rather than having a (very) long list of explicit exceptions from the full recommended ruleset?

I like this idea! It can be implemented either as a redocly.yaml file or CLI args. I picked additional cli args as a simpler approach for now. Fine-grained rule settings might be more useful later.

is the recommended ruleset the minimum required to be OpenAPI 3.0.1 spec compliant? I'd have guessed that was what minimal was for, but it sounds like that's not the case

I don't think I can point single reference implementation that would confirm 100% spec compliance. Actually, there are many different implementations. It's my first time with Redocly, but it does comprehensive validation. For example, it validated and pointed out request examples that don't comply with the request schema.

[alxndrsn]

#1644 may cause conflicts with this PR, but the changes should be simple enough to iron out.

[alxndrsn]

I don't think I can point single reference implementation that would confirm 100% spec compliance.

@jbylina given this, and that your original aim is:

I would like to improve the OpenAPI docs so that I can use them to generate an odk API client.

can you give any more info on how you're trying to generate the API client?

[alxndrsn]

@jbylina would the ruleset at https://github.com/Redocly/redocly-cli-cookbook/tree/main/rulesets/spec-compliant be a suitable target?

It looks like there's a built-in spec ruleset (defined at https://github.com/Redocly/redocly-cli/blob/2367722a9fb173e55626dccbdac7b6694dd8b199/packages/core/src/config/spec.ts) which confusingly the author of spec-compliant ruleset considers to be inadequate: Redocly/redocly-cli-cookbook#12

It also seems like the current YAML parser that redocly uses is insufficient to enforce the full spec requirements, specifically re: Redocly/redocly-cli#1347. If this is important for consumers of the ODK docs then we could likely enforce this client easily with an additional check of our own.

[alxndrsn]

#1688 may also help