From fb4445bf53a6625761bc1dfe804a91867cf019e4 Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Thu, 28 Mar 2024 10:14:02 +0530 Subject: [PATCH] Add documentation details on the API documentation Signed-off-by: Akashdeep Dhar --- docs/webhook2fedmsg/apid.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/webhook2fedmsg/apid.rst diff --git a/docs/webhook2fedmsg/apid.rst b/docs/webhook2fedmsg/apid.rst new file mode 100644 index 0000000..3ddc7d4 --- /dev/null +++ b/docs/webhook2fedmsg/apid.rst @@ -0,0 +1,26 @@ +.. _apid: + +API documentation +================= + +Suggestion +---------- + +It is strongly recommended to automate the process of documenting API routes +using libraries like Swagger UI and a documentation format that is compliant +with the OpenAPI standards. To that extent, the API service library should be +selected in a way that causes little to no concern in integrating an automated +API documentation system. + +This can ensure that not only little effort is spent on the documentation but +can also help avoid human errors that might creep in when documenting the +routes, the expected request contents and the inferred response contents. The +API documentation might need a test access token with limited privileges if +present beyond authentication. + +Technologies +------------ + +1. `Swagger UI `_ +2. `OpenAPI standard `_ +