Make the pipeline variable example responses match the API

What does this MR do?

The pipelines and pipeline schedules APIs present every variable with API::Entities::Ci::Variable. The entity always exposes variable_type, and it exposes raw for any record that responds to raw?. A pipeline's variables come from its pipeline_variables artifact as Ci::PipelineVariableItem objects, whose raw defaults to false and whose variable_type defaults to env_var, or from Ci::PipelineVariable rows when it has no such artifact. Ci::PipelineVariable and Ci::PipelineScheduleVariable both include Ci::RawVariable, and both tables store raw as boolean DEFAULT false NOT NULL. Every response on these routes therefore carries both attributes.

Five example responses left out raw, and two of the variables in them also left out variable_type. This MR adds them:

• "Retrieve pipeline variables" in doc/api/pipelines.md: raw on both variables, and variable_type on the second.
• The examples for creating, retrieving, updating and deleting a pipeline schedule variable in doc/api/pipeline_schedules.md: raw on all four, and variable_type on the delete example.

Every added raw is false, the default for all three kinds of record, which is also what the "Retrieve a pipeline schedule" example on the same page already shows for its variable, rendered by the same entity. Only example blocks change: no table rows and no prose.

doc/api/openapi/openapi_v3.yaml already lists raw under APIEntitiesCiVariable, the schema all five routes reference, so the generated reference needs no change. That schema lists all nine attributes the entity can expose, including hidden, protected, masked, environment_scope and description, which the entity never sends for these records, so the examples are where a reader sees the four these routes actually return.

The response table under "Retrieve a variable for a pipeline schedule" lists key, value and variable_type but not raw. I left it alone, since the API docs are moving toward the generated spec rather than growing their Markdown tables. If you would like the table and the example to match, I can add the row here.

The request table under "Update a variable for a pipeline schedule" also marks value as required, while the route declares it optional; I can correct that here too if you like.

I found this while adding raw to PipelineVariable in the Go API client, in gitlab-org/api/client-go!3085 (merged), where the reviewer asked for an MR that updates the API documentation for the fields that MR adds.

How I checked what these routes return

• Code, at master 60d9f74b: lib/api/ci/pipelines.rb presents pipeline.variables and lib/api/ci/pipeline_schedules.rb presents the created, retrieved, updated and destroyed schedule variable, all with Entities::Ci::Variable. Ci::Pipeline#variables returns Ci::PipelineVariableItem objects read from the pipeline's pipeline_variables artifact, which Gitlab::Ci::Pipeline::Build::PipelineVariablesArtifactBuilder writes for every pipeline created with variables, and falls back to Ci::PipelineVariable rows. app/models/ci/pipeline_variable_item.rb declares raw with a default of false, aliased as raw?, and variable_type with a default of env_var. lib/api/entities/ci/variable.rb exposes raw under if: ->(entity, _) { entity.respond_to?(:raw?) }. app/models/ci/pipeline_variable.rb and app/models/ci/pipeline_schedule_variable.rb both include Ci::RawVariable, and db/structure.sql has raw boolean DEFAULT false NOT NULL on p_ci_pipeline_variables and ci_pipeline_schedule_variables.
• Existing spec: spec/requests/api/ci/pipelines_spec.rb, whose create_or_replace_pipeline_variables helper stores the variables as that artifact, expects exactly variable_type, key, value and raw (false) from GET /projects/:id/pipelines/:pipeline_id/variables. I ran that example on this branch: it passes.
• Schedule variables: spec/requests/api/ci/pipeline_schedules_spec.rb checks key, value and variable_type one by one and matches the pipeline_schedule_variable schema, which allows raw without requiring it, so nothing there pins raw. I ran a throwaway request spec, not part of this MR, that creates a variable with POST, then retrieves, updates and deletes it, and compares each whole JSON response. All four were exactly key, variable_type, value and raw: false, which is what the four examples now show.
• Values: neither the create nor the update route for pipeline schedule variables accepts raw, so a variable created through them keeps the default.

Lint

• scripts/lint-doc.sh doc/api/pipelines.md doc/api/pipeline_schedules.md, run in the lint image the script names (markdownlint-cli2 0.23.2, Vale 3.21.0): passed, with no markdownlint issues and no Vale errors.
• Vale at warning level on both pages, on this branch and on master: no alerts on either.
• lychee --offline --no-progress --include-fragments on both pages, as the docs-lint links job runs it: 0 errors.
• Every JSON block on both pages parses with jq: 11 on the pipelines page and 12 on the pipeline schedules page.

Related issues

Related to gitlab-org/api/client-go!3085 (merged)

Author's checklist

• Optional. Consider taking the GitLab Technical Writing Fundamentals course.
• Follow the:
  • Documentation process.
  • Documentation guidelines.
  • Style Guide.
• If you're adding a new page, add the product availability details under the H1 topic title.
• If you are a GitLab team member, request a review based on:
  • The documentation page's metadata.
  • The associated Technical Writer.

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

• ~"frontend"
• ~"backend"
• ~"type::bug"
• ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

• If the content requires it, ensure the information is reviewed by a subject matter expert.
• Technical writer review items:
  • Ensure docs metadata is present and up-to-date.
  • Ensure the appropriate labels are added to this MR.
  • Ensure a release milestone is set.
  • If relevant to this MR, ensure content topic type principles are in use, including:
    • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
    • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
    • Any task steps should be written as a numbered list.
    • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
• Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.