Useful OpenAPI notes and ideas

README.md

• Linting an open api description

  npx @redocly/cli lint swagger/openapi.json

• Generating doc hmtl page for the description

  npx @redocly/cli build-docs swagger/openapi.json

• Splitting a open api description in multiple files

  npx @redocly/cli split swagger/openapi.json --outDir=openapi-test/

• Diffing open api descriptions

  oasdiff diff swagger/openapi.json swagger/openapi-copy.json

  NOTE: the above might fail in some cases, even when redocly reports the spec as valid. Finding the culprit path:

  #!/usr/bin/env fish
  
  for path in (cat openapi.json | jq -r '.paths | keys[]') do
    cat openapi.json | jq --arg path "$path" '.paths |= with_entries(select(.key == $path))' > small.json
    cp small.json small-copy.json
    if ! oasdiff diff small.json small-copy.json &> /dev/null
      echo "Error on path: $path"
    end
  end