From 0e4d02e11a6dfc4e381556a93b2eeb3860f62f2a Mon Sep 17 00:00:00 2001 From: Zeegaan Date: Wed, 22 May 2024 13:52:06 +0200 Subject: [PATCH 1/6] Add initial documentation --- .../documenting-your-controllers.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md diff --git a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md new file mode 100644 index 00000000000..d5c761488bd --- /dev/null +++ b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md @@ -0,0 +1,68 @@ +# Documenting your controllers +Documenting your API controllers using Swagger in Umbraco Version 14 simplifies the creation of detailed and interactive API documentation. By adding Swagger attributes, you automatically generate comprehensive information about routes, parameters, and response types, enhancing the developer experience and ensuring clarity and consistency in your API documentation. + + +## ApiExplorerSettings +With the `ApiExplorerSettings` attribute, we can put all of our endpoints into a given group, this is a nice way of organizing our endpoints in the Swagger UI. + +```csharp +## ProducesResponseType Attribute + +Use [ProducesResponseType] to specify the possible responses for each action method. This helps Swagger generate accurate documentation for your API. +For example, in the GetItem method: +```csharp +[HttpGet("{id:guid}")] +[ProducesResponseType(StatusCodes.Status200OK)] +[ProducesResponseType(StatusCodes.Status404NotFound)] +public IActionResult GetItem(Guid id) +{ +// Method implementation +} +``` + +Here, `[ProducesResponseType]` specifies that a 200 OK response will return a MyItem, and a 404 Not Found response will return a ProblemDetails. + +## Example Documentation for Each Controller Method: +TO get a feel for how you'd document each of your controller methods, here are some examples of how you might document each of the operations for a simple API controller, this controller is from the [Creating your own api](./create-your-own-api.md) article: +### GetAllItems +```csharp +[HttpGet] +[ProducesResponseType>(StatusCodes.Status200OK)] +public IActionResult GetAllItems(int skip = 0, int take = 10) +``` +### GetItem + +```csharp +[HttpGet("{id:guid}")] +[ProducesResponseType(StatusCodes.Status200OK)] +[ProducesResponseType(StatusCodes.Status404NotFound)] +public IActionResult GetItem(Guid id) +``` +### CreateItem + +```csharp +[HttpPost] +[ProducesResponseType(StatusCodes.Status201Created)] +[ProducesResponseType(StatusCodes.Status400BadRequest)] +public IActionResult CreateItem(string value) +``` +### UpdateItem + +```csharp +[HttpPut("{id:guid}")] +[ProducesResponseType(StatusCodes.Status200OK)] +[ProducesResponseType(StatusCodes.Status400BadRequest)] +[ProducesResponseType(StatusCodes.Status404NotFound)] +public IActionResult UpdateItem(Guid id, string value) +``` +### DeleteItem + +```csharp +[HttpDelete("{id:guid}")] +[ProducesResponseType(StatusCodes.Status200OK)] +[ProducesResponseType(StatusCodes.Status404NotFound)] +public IActionResult DeleteItem(Guid id) +``` +## Verifying the changes +Run your application and navigate to the Swagger UI (typically found at /swagger). +Verify that your API documentation is correctly displaying the routes, parameters, and response types. From 17fa511f7c86c416f573857ff860993214b6bdd5 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Fri, 24 May 2024 10:18:13 +0200 Subject: [PATCH 2/6] Update 14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md --- .../fundamentals/backoffice/documenting-your-controllers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md index d5c761488bd..9915b26132e 100644 --- a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md +++ b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md @@ -1,5 +1,5 @@ # Documenting your controllers -Documenting your API controllers using Swagger in Umbraco Version 14 simplifies the creation of detailed and interactive API documentation. By adding Swagger attributes, you automatically generate comprehensive information about routes, parameters, and response types, enhancing the developer experience and ensuring clarity and consistency in your API documentation. +Documenting your API controllers using Swagger in Umbraco Version 14 simplifies the creation of detailed and interactive API documentation. Adding Swagger attributes automatically generates comprehensive information about routes, parameters, and response types. This will enhance the developer experience and ensure clarity and consistency in your API documentation. ## ApiExplorerSettings From a32dde6b82539441f021f18b04da3ee91067c4ca Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Fri, 24 May 2024 10:18:18 +0200 Subject: [PATCH 3/6] Update 14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md --- .../fundamentals/backoffice/documenting-your-controllers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md index 9915b26132e..6fae006ae64 100644 --- a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md +++ b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md @@ -22,7 +22,7 @@ public IActionResult GetItem(Guid id) Here, `[ProducesResponseType]` specifies that a 200 OK response will return a MyItem, and a 404 Not Found response will return a ProblemDetails. -## Example Documentation for Each Controller Method: +## Example Documentation for Each Controller Method TO get a feel for how you'd document each of your controller methods, here are some examples of how you might document each of the operations for a simple API controller, this controller is from the [Creating your own api](./create-your-own-api.md) article: ### GetAllItems ```csharp From f901a38b38c6d8e5091556224760bcf13408c205 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Fri, 24 May 2024 10:18:32 +0200 Subject: [PATCH 4/6] Update 14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md --- .../fundamentals/backoffice/documenting-your-controllers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md index 6fae006ae64..32d202ac894 100644 --- a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md +++ b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md @@ -3,7 +3,7 @@ Documenting your API controllers using Swagger in Umbraco Version 14 simplifies ## ApiExplorerSettings -With the `ApiExplorerSettings` attribute, we can put all of our endpoints into a given group, this is a nice way of organizing our endpoints in the Swagger UI. +With the `ApiExplorerSettings` attribute, we can put all our endpoints into a given group. This is a nice way of organizing our endpoints in the Swagger UI. ```csharp ## ProducesResponseType Attribute From 389c34374399773de4f727f6d6e10b74eef59d34 Mon Sep 17 00:00:00 2001 From: jonat123 <54025331+jonat123@users.noreply.github.com> Date: Fri, 24 May 2024 10:18:40 +0200 Subject: [PATCH 5/6] Update 14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md --- .../fundamentals/backoffice/documenting-your-controllers.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md index 32d202ac894..2b9f851940f 100644 --- a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md +++ b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md @@ -23,7 +23,8 @@ public IActionResult GetItem(Guid id) Here, `[ProducesResponseType]` specifies that a 200 OK response will return a MyItem, and a 404 Not Found response will return a ProblemDetails. ## Example Documentation for Each Controller Method -TO get a feel for how you'd document each of your controller methods, here are some examples of how you might document each of the operations for a simple API controller, this controller is from the [Creating your own api](./create-your-own-api.md) article: +To get an idea of how to document each controller method, below are some examples of how to document each operation for an API controller. +The controller is from the [Creating your own API article](./create-your-own-api.md) ### GetAllItems ```csharp [HttpGet] From dc006578dc8699a3410d838c451b2ce40b8a81a8 Mon Sep 17 00:00:00 2001 From: Zeegaan Date: Fri, 24 May 2024 10:40:46 +0200 Subject: [PATCH 6/6] Add missing example --- .../fundamentals/backoffice/documenting-your-controllers.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md index 2b9f851940f..6ca1019714f 100644 --- a/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md +++ b/14/umbraco-cms/fundamentals/backoffice/documenting-your-controllers.md @@ -6,6 +6,9 @@ Documenting your API controllers using Swagger in Umbraco Version 14 simplifies With the `ApiExplorerSettings` attribute, we can put all our endpoints into a given group. This is a nice way of organizing our endpoints in the Swagger UI. ```csharp +[ApiExplorerSettings(GroupName = "My item API")] +public class MyItemApiController : ManagementApiControllerBase +``` ## ProducesResponseType Attribute Use [ProducesResponseType] to specify the possible responses for each action method. This helps Swagger generate accurate documentation for your API.