Here are my notes on using swagger-php to generate API docs from code annotations.

I've reviewed the pages in question and made a series of edits to complete this task. To summarize, I:

Thanks for calling that out, @Aklapper! I've added a note to the checklist.

To clarify: The Core REST API needs to be documented on mediawiki.org, but it will not be included in the dev portal. The Unified Wikimedia API needs to be documented on the dev portal but not on mediawiki.org. My assumption was that the automated API doc solution would be reusable for both these APIs.

I've updated the task description with the requirements as I see them. Feel free to update as needed!

It seems that the relevant section of Requests_for_comment/Standards_for_external_services has been moved to Wikimedia services guideline. I'd recommend adding the two subsections (Abstractions: A priori versus a posteriori and Pre-generating page-derived data) under Development policies.

Nice find, @Pchelolo! It seems like the docs site for that library is down, but the issue pointed at at this web archive link to view the docs in the meantime. I think using a library like this would meet our requirements, especially if we can find a way to render the spec within MediaWiki.

@nnikkhoui Thanks! That's a good callout. The doc lists the 500 error as a possible response, but I've added a note to the minor type to make that behavior more clear.

Considering that we're moving this endpoint to v0, I'd suggest removing the documentation step from this task in favor of handling the docs in the task that moves this endpoint to v1.

I've updated the docs to include the new limits. @nnikkhoui, can you review this changeset to make sure everything is correct?

Reviewed synchronously with Evan.

@Clarakosi The draft looks great! The comparison table is set up nicely, and the doc is easy to understand. Nice work!

Updated the wiki page for the REST API and reviewed with Clara.

I've applied review feedback (Thanks, Bill and Nikki!) and removed the Draft banner from the doc.

@BPirkle, the wiki page now includes the additions and changes we discussed last week. Would you mind reading through it again and making sure everything looks good?

@eprodromou Can you review the text here?

From a documentation perspective, it makes sense to version the docs by major version. Major versions ensure backwards compatibility and give developers confidence in the API. We'll need to incorporate this into our specifications for the automated API docs.

Sounds good to me! I'll open a patch.

Updated the docs with the minor property.

Interesting results: When I excluded the Code of Conduct page from the Doxygen output, the new pages appeared nested under the Introduction page, which is the outcome I was expecting originally. However, when I added another Markdown file (converting one of the /docs .txt files, for example), the new page appeared nested under that Markdown page. I experimented with creating a dedicated landing page, but it seems that Doxygen randomly selects a Markdown page under which to nest the pages tagged with @ingroup. Since we eventually plan to convert the /docs .txt files to Markdown, I don't think excluding the Code of Conduct is a viable solution here.

Updated the docs with the limit of 1000.

I should have clarified: Looking at the implementation, I'm seeing a limit of 500, which appears to conflict with the task description.

Perfect, thanks!

Which standard are we using for language codes? Is there a link to the list of available codes?

I've updated the task description to be more specific and reflect a similar amount of work to the examples listed here.

Updated the docs with a limit of 500 for all history count types.

I've opened a patch for the new exclude pattern, but I wasn't able to find a way to get the class-level Markdown files to not nest under the code of conduct while still having the Markdown formatting render correctly. We'll need to decide whether to revert https://gerrit.wikimedia.org/r/539439 if we can't find a solution for this.

It looks like https://gerrit.wikimedia.org/r/539439 did not completely solve this issue. The new pages now appear nested under the code of conduct page. I'll experiment with how to resolve this, but I'm not sure how this is happening. Additionally, it looks like we'll need another exclude pattern to account for https://doc.wikimedia.org/mediawiki-core/master/php/md_maintenance_benchmarks_README.html

Always happy to discuss this! Here are my notes:

Updated the docs with the new filter names. I didn't include a deprecation notice in the docs because the endpoint is still fairly new, but I can go back and add one if we think it's necessary. In general, I'd like to include an API changelog in the docs, either imported from source or maintained on the wiki.

Updated docs to reflect these changes.

Updated docs to reflect this change

The docs should reflect the current behavior of the endpoint, so we shouldn't change the doc until the functionality is changed.

Do we have a sense of whether we're standardizing on snake case or camel case? For example, the spec for this endpoint has properties in snake case, while the spec for the get media links endpoint has properties in camel case.

Yep! I'll do that later today.

Nice! I was able to get the paragraphs to render correctly by putting @ingroup FileRepo above the title, but, as a result, Doxygen nests the file under the filename in the sidebar:

Hi @Tgr, Thanks for creating this task! Can you elaborate on the documentation needs for "update documentation affected by the new entry point (nice URLs, web server security...)"?

In documenting this endpoint, I've run into a few possible improvements to the user experience.

Updated the documentation with a 403 response for this endpoint. (Compare revisions docs)

Updated the docs for the get page history and get revision endpoints as shown here. Let me know if this is incorrect or insufficient.