Skip to content

fix(ocs): Minor improvements to the OCS OpenAPI documentation #13210

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix(ocs): Minor improvements to the OCS OpenAPI documentation #13210

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions developer_manual/client_apis/OCS/ocs-openapi.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
OCS OpenAPI tutorial
====================

This page explains you how you can add OpenAPI support to your app such that you can automatically generated an OpenAPI specification from your server code.
This page explains you how you can add OpenAPI support to your app so that you can automatically generate an OpenAPI specification from your server code.

Please read the whole tutorial before starting to adapt your app.

Do not be afraid that you do not know everything from the start.
Don't be afraid that you do not know everything from the start.
The openapi-extractor tool gives you many warnings and fails if there is something utterly broken that would not work.
Let the tool run and it will tell you if there is something wrong.
Psalm will also help you validate your changes to ensure that nothing is broken.
Expand Down Expand Up @@ -544,10 +544,26 @@ It is best to start with helper methods that are used multiple times like the ``
...
}

The return type for [`DataResponse`](https://github.com/nextcloud/server/blob/master/lib/public/AppFramework/Http/DataResponse.php) and other inheritors of [`Response`](https://github.com/nextcloud/server/blob/master/lib/public/AppFramework/Http/Response.php) expect different arguments. See their class annotations in the code. The following table lists some common ones:

+--------------------------+----------------------------+
| Response inheritor class | Expected arguments |
+--------------------------+----------------------------+
| `DataResponse` | status code, data, headers |
+--------------------------+----------------------------+
| `RedirectResponse` | status code, headers |
+--------------------------+----------------------------+
| `StreamResponse` | status code, headers |
+--------------------------+----------------------------+
| `TemplateResponse` | status code, headers |
+--------------------------+----------------------------+

Afterwards you can add the return types to all the other methods.
If two different status codes return the same data structure and headers, you can use the union operator to indicate it: ``Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND``.

You are required to add a description for every status code returned by the method.
If you wonder about the return type syntax, the psalm documentation on [typing in Psalm](https://psalm.dev/docs/annotating_code/typing_in_psalm/) might be helpful.

You have to add a description for every status code returned by the method.

.. code-block:: php

Expand Down
Loading