Hi @Yessmine_ghars, My apologies! This isn't a good task to work on right now since it needs more discussion from the team before it can be started. I'll add that as a clarification to the task.

@aaron & @BPirkle -- The scope of this ticket should really focus on how we add examples for request parameters to the MW framework, and what translation support might look like. This will also be required to get the MediaWIki spec up to snuff in terms of meeting the linting rules.

Estimation notes:

• For now, examples can be hard-coded to English for now. There is nuance about whether these examples will work across other languages, but we will figure that out as a subsequent work stream.
• We do not yet have the ability to specify requests parameters; this ticket should figure that out (at the framework level).
• Assume this will cover implementation -- if it gets weird or overly complicated, stop and decide how we can break it down further.
• Proposed theme for examples: Spaaaace! (Earth exists on every Wikipedia). Or Science (names typically are not translated, like Albert Einstein).
• Alex has some pending patches for examples of response parameter schemas; we can get inspiration from that: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1271873

@apaskulin , the team talked about using your code from this patch for examples of response parameter schemas. Checking if there are any other existing examples we should be aware of? If there were any observations or things to keep in mind that are relevant to this task when you were coming up with those examples, feel free to share!

I understand from @HCoplin-WMF that she will combine this task with https://phabricator.wikimedia.org/T392154 and clean up the requirements between the two tasks so I will watch out for that update.

Hi @KineticPelagic, For ideas for request parameter examples, you can:

• look at the examples in the response schemas. Once 1275490 is merged, there should be a complete set in the Schema directory.
• look at the manually-created docs on mediawiki.org which includes request examples.

I'm also happy to help with adding request examples once the system for adding them is in place.

T392154 doesn't seem to overlap with this task at all.

Thank you, @apaskulin.

And thanks for the clarification - I realize I got mixed up when Halley was sharing her screen and I saw "Support tags" from https://phabricator.wikimedia.org/T425427, which is not the same as "Support examples" here!

In T420988#11894845, @apaskulin wrote:

Hi @KineticPelagic, For ideas for request parameter examples, you can:

• look at the examples in the response schemas. Once 1275490 is merged, there should be a complete set in the Schema directory.
• look at the manually-created docs on mediawiki.org which includes request examples.

I'm also happy to help with adding request examples once the system for adding them is in place.

T392154 doesn't seem to overlap with this task at all.

Change #1286287 had a related patch set uploaded (by KineticPelagic; author: KineticPelagic):

[mediawiki/core@master] REST: Add OpenAPI request example support

https://gerrit.wikimedia.org/r/1286287

For code reviewers, I would like to get your confirmation on this point. As I mentioned in the Gerrit commit message:

Cookie Parameters: The task description mentioned cookie examples.
While OpenAPI supports in: cookie, Validator::KNOWN_PARAM_SOURCES
currently does not support cookie as a valid parameter source. See:
https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/refs/heads/master/includes/Rest/Validator/Validator.php#49.
Adding cookie examples would require first building framework-level
support to parse and validate cookies via ParamValidator. I decided
that this architectural expansion was out of scope for this task. If
you would like me to create a new ticket for this work, please let me
know.

@KineticPelagic I agree with you, looking into the callbacks from ParamValidator It makes sense to me to do this in another task.
I am not sure either if the cookie parser should be an extension of the header parser or a totally separated file, it looks to me that there is a difference of what is considered the value between declaring a cookie my_string name in header location and a my_string name in cookie location.

Agreed on doing cookie support separately.

Or maybe not at all. I'm skeptical of the value, and of unnecessarily entwining authentication-related information (which may differ per-wiki) into the parameter section of the OpenAPI specs. If cookies were application-logic-related portions of our APIs related to the primary purpose of the endpoint itself, then it'd make sense to do so. In our situation, I'll have to be convinced that it is relevant or helpful.

Change #1286287 merged by jenkins-bot:

[mediawiki/core@master] REST: Add OpenAPI request example support

https://gerrit.wikimedia.org/r/1286287

Change #1286534 had a related patch set uploaded (by KineticPelagic; author: KineticPelagic):

[mediawiki/core@master] REST: Support OpenAPI request examples - Update version

https://gerrit.wikimedia.org/r/1286534

Change #1286534 merged by jenkins-bot:

[mediawiki/core@master] REST: Support OpenAPI request examples - Update version

https://gerrit.wikimedia.org/r/1286534

Thanks for the review, @MGoncalves-WMF !

@BPirkle , great point that there is not necessarily logical reasoning to entwine the parameter section of an OpenAPI spec with information that relates to authentication and that can differ by wiki. We might go off-track if specs start to describe infrastructure concerns, such as how a user is authenticated, inside what we intend as API contract documentation.

Is there documentation for how to add these examples?

Marking as resolved as part of sprint close out.

@apaskulin , not yet. Shall we have a task to make this documentation, @KBach ?

@KineticPelagic @apaskulin thank you for bringing this up. This falls under T418196, specifically "Generating an OpenAPI spec using in-code tags, including examples", and "Defining JSON response examples". I discussed this with @HCoplin-WMF and we'll be planning this work separately, under the other epic.

In T420988#11940564, @KBach wrote:

@KineticPelagic @apaskulin thank you for bringing this up. This falls under T418196, specifically "Generating an OpenAPI spec using in-code tags, including examples", and "Defining JSON response examples". I discussed this with @HCoplin-WMF and we'll be planning this work separately, under the other epic.

I look forward to continuing to make it easier for developers to use capabilities through the REST API framework, through both documentation and the developer experience.

The proposed hackathon / Modulathon / RESTathon that the team is planning could help alert us to points of confusion that we could use T418196: [5.2.8 Epic]: REST API Framework Documentation to address.

In T420988#11936377, @apaskulin wrote:

Is there documentation for how to add these examples?

I will defer to the epic Kamil mentioned to prioritize my work in progress. In the meantime before writing up full-fledged documentation on your question, let me start to give a sense here on how to add an example to an existing parameter, @apaskulin .

For example for a header parameter:
We can add the Handler::PARAM_EXAMPLE key below the description in getHeaderParamSettings(). The added line could look like Handler::PARAM_EXAMPLE => 'es, en-US;q=0.8',.

For example for a query parameter:
We can add the Handler::PARAM_EXAMPLE key below the description in getParamSettings(). The added line could look like Handler::PARAM_EXAMPLE => 'Earth',.

For example for a path parameter:
We can add the Handler::PARAM_EXAMPLE key below the description in getParamSettings(). The added line could look like Handler::PARAM_EXAMPLE => new MessageValue( 'rest-param-example-page-title' ),, given that en.json and qqq.json have registered the message key 'rest-param-example-page-title'.

For example for a body property:
We can add the Handler::PARAM_EXAMPLE key below the description in getBodyParamSettings(). The added line for the title property could look like Handler::PARAM_EXAMPLE => 'Project_Mars',.

For complex properties such as tags, which is an array, you can provide an array example, as shown below.

1 'tags' => [
2     self::PARAM_SOURCE => 'body',
3     ParamValidator::PARAM_TYPE => 'array',
4     Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-tags' ),
5     Handler::PARAM_EXAMPLE => [ 'Astronomy', 'Space' ], // <--- Array example
6 ],

PARAM_EXAMPLE behaves similarly to PARAM_DESCRIPTION. The framework’s OpenAPI generator will use PARAM_EXAMPLE as part of building the OpenAPI specification.

This is super helpful. Thanks!

Change #1301299 had a related patch set uploaded (by KineticPelagic; author: KineticPelagic):

[mediawiki/core@master] REST: Allow 'rest-param-example' in `RestStructureTest`

https://gerrit.wikimedia.org/r/1301299

Change #1301299 merged by jenkins-bot:

[mediawiki/core@master] REST: Allow 'rest-param-example' in `RestStructureTest`

https://gerrit.wikimedia.org/r/1301299