fixup! WIP: Add OpenAPI tutorial

Author: provokateurin

developer_manual/client_apis/OCS/ocs-openapi.rst

@@ -41,9 +41,9 @@ Tips and tricks
 ---------------
 
 The openapi-extractor tool forces you to set descriptions everywhere.
-To ease the adoption process you can set the `--allow-missing-docs` flag to ignore those problems.
+To ease the adoption process you can set the ``--allow-missing-docs`` flag to ignore those problems.
 
-The tool also only shows errors one by one by default, but you can also let it show you all problems at once using the `--continue-on-error`.
+The tool also only shows errors one by one by default, but you can also let it show you all problems at once using the ``--continue-on-error``.
 
 It is advised to use neither of the mentioned flags to generate the final specification.
 They hide problems that your code has.
@@ -125,21 +125,21 @@ Psalm will catch these problems for you if you configured the issue handlers men
             ];
         }
 
-PREFER to use `null` to represent empty data
+PREFER to use ``null`` to represent empty data
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Your API should be designed in a way that represents empty data with `null`.
+Your API should be designed in a way that represents empty data with ``null``.
 
 There is a problem with PHP and arrays that get converted to JSON.
 JSON has lists and objects while PHP only has arrays.
-If you were to return an empty array in PHP it will always turn into `[]` in JSON.
+If you were to return an empty array in PHP it will always turn into ``[]`` in JSON.
 This is not a problem for endpoints that always return lists, but most endpoints return a single JSON object.
-For those endpoints returning `[]` in PHP is a problem because the consumer will either get `[]` or `{...}` which is hard to handle.
+For those endpoints returning ``[]`` in PHP is a problem because the consumer will either get ``[]`` or ``{...}`` which is hard to handle.
 
-If you are not able to use `null` for whatever reason, use `new \stdClass()` instead.
-It will get correctly converted into `{}` in the JSON response on Nextcloud 28 and later.
+If you are not able to use ``null`` for whatever reason, use ``new \stdClass()`` instead.
+It will get correctly converted into ``{}`` in the JSON response on Nextcloud 28 and later.
 
-If you are working with an existing API where you can not break compatibility, you can also type the result as `array<empty>`.
+If you are working with an existing API where you can not break compatibility, you can also type the result as ``array<empty>``.
 
 .. collapse:: Examples
 
@@ -213,7 +213,7 @@ Return valid responses with an error message instead.
 DO use the same data structures for the same group of responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Using `null` to represent empty data is encouraged.
+Using ``null`` to represent empty data is encouraged.
 All 2xx responses should return the same data structure and all 4xx should also return the same data structure.
 
 .. collapse:: Examples
@@ -272,11 +272,11 @@ All 2xx responses should return the same data structure and all 4xx should also
             }
         }
 
-DO NOT use the `addHeader` method for setting headers for your responses
+DO NOT use the ``addHeader`` method for setting headers for your responses
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Right now it is not possible for psalm to trace headers you set this way, so they will not be validated by psalm.
-Use the `setHeaders` method instead.
+Use the ``setHeaders`` method instead.
 
 .. collapse:: Examples
 
@@ -525,7 +525,7 @@ What you want to do now is to firstly create the correct parameter annotations a
 The next step is to add the return types.
 This is the most important step to get your API documented.
 
-It is best to start with helper methods that are used multiple times like the `formatTodo` method in this example:
+It is best to start with helper methods that are used multiple times like the ``formatTodo`` method in this example:
 
 .. code-block:: php
 
@@ -537,7 +537,7 @@ It is best to start with helper methods that are used multiple times like the `f
     }
 
 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`.
+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.
 
@@ -600,7 +600,7 @@ How to add response definitions to share type definitions
 
 In the previous steps we have been re-using the same data structure multiple times, but it was copied every time.
 This is tedious and error prone, therefore we want to create some shared type definitions.
-Create a new file called `ResponseDefinitions.php` in the `lib` folder of your app.
+Create a new file called ``ResponseDefinitions.php`` in the ``lib`` folder of your app.
 It will only work with that file name at that location.
 
 .. code-block:: php
@@ -628,14 +628,14 @@ To import and use the type definition you have to import it in your controller:
         ...
     }
 
-Now you can replace every occurrence of `array{id: int, title: string, description: ?string, image: ?string}` with `TodoItem`.
+Now you can replace every occurrence of ``array{id: int, title: string, description: ?string, image: ?string}`` with ``TodoItem``.
 
 How to handle exceptions
 ------------------------
 
 Sometimes you want to end with an exception instead of returning a response.
 It is better to not do it, but when migrating existing APIs you might have to deal with exceptions.
-For this example our `update` will throw an exception when the ETag does not match:
+For this example our ``update`` will throw an exception when the ETag does not match:
 
 .. code-block:: php
 
@@ -670,7 +670,7 @@ How to ignore certain endpoints
 -------------------------------
 
 The tool already ignores all the endpoints that are not reachable from the outside, but some apps have reachable endpoints that are not APIs (e.g. serving some HTML).
-To ignore those you can add the `#[IgnoreOpenAPI]` attribute or if you still support PHP 7 the `@IgnoreOpenAPI` annotation to the controller method or the controller class:
+To ignore those you can add the ``#[IgnoreOpenAPI]`` attribute or if you still support PHP 7 the ``@IgnoreOpenAPI`` annotation to the controller method or the controller class:
 
 .. code-block:: php
 
@@ -726,6 +726,6 @@ The capabilities will automatically appear in the generated specification.
 How to generate the specification
 ---------------------------------
 
-If you followed the installation instructions for openapi-extractor you can run `composer exec generate-spec` in your apps root folder and you will have a new file called `openapi.json`.
+If you followed the installation instructions for openapi-extractor you can run ``composer exec generate-spec`` in your apps root folder and you will have a new file called ``openapi.json``.
 If the tool fails somewhere it will tell you what is wrong and often times also how to fix the problem.
 Additionally you should run psalm to check for any problems.