API architecture

this guide explains how the api documentation architecture works in the ir engine codebase, including its components and generation process overview the ir engine uses feathers swagger https //github com/feathersjs ecosystem/feathers swagger to automatically generate openapi documentation from service definitions and schema files this creates a declarative approach where documentation is generated from code rather than maintained separately for detailed guidance on creating effective api documentation, see the documenting endpoints docid 1jbo9mb4njisxg5a2p pa guide api documentation workflow graph td subgraph "developer actions" a\[define schema] >|creates| b\[schema file\<br> schema ts] c\[write docs] >|creates| d\[docs file\<br> docs ts] e\[implement service] >|creates| f\[service file\<br> ts] g\[implement hooks] >|creates| h\[hooks file\<br> hooks ts] end subgraph "documentation generation" b >|structure| i\[service registration] d >|details| i f >|connection| i h >|logic| i i >|feeds| j\[feathers swagger] k\[openapi config] >|settings| j j >|generates| l\[openapi docs] end subgraph "user access" l >|served at| m\["openapi endpoint"] m >|displays in| n\[swagger ui] end classdef files fill #553366,stroke #aa77aa,stroke width 1px,color #ffffff; classdef process fill #335566,stroke #7799aa,stroke width 1px,color #ffffff; classdef output fill #335533,stroke #779955,stroke width 1px,color #ffffff; class b,d,f,h files; class i,j,k process; class l,m,n output; this diagram shows how components work together to generate api documentation, from developer files to the swagger ui documentation generation process the openapi documentation in ir engine is generated through the following process schema definition each service has a schema file that defines its data structure and available methods documentation enhancement each service also has a documentation file that provides additional details without custom descriptions in this step, your api documentation will only contain generic placeholders replace default descriptions with meaningful, context specific information include examples and parameter descriptions to help api consumers understand how to use your api service registration when a service is registered, it includes its documentation automatic generation the feathers swagger package automatically generates the openapi documentation based on these components documentation serving the documentation is served at the /openapi endpoint ( localhost 3030/openapi in your local deployment) this process ensures that the api documentation stays in sync with the actual implementation, as it's generated directly from the code the quality and usefulness of the documentation depend on the effort put into step 2 key components the api documentation system in ir engine consists of several key components schema files ( packages/common/src/schemas/\[category]/\[name] schema ts ) define data structures, available methods, and validation rules example packages/common/src/schemas/cluster/build status schema ts contains path definitions, method lists, and data schemas documentation files ( packages/server core/src/\[category]/\[name]/\[name] docs ts ) provide additional documentation details like descriptions, examples, and parameter information example packages/server core/src/cluster/build status/build status docs ts use createswaggerserviceoptions() to define documentation options without proper descriptions in these files, the api documentation will only contain generic placeholders service registration ( packages/server core/src/\[category]/\[name]/\[name] ts ) connect schemas and documentation to services example packages/server core/src/cluster/build status/build status ts include documentation when registering the service with app use() hooks ( packages/server core/src/\[category]/\[name]/\[name] hooks ts ) contain most of the service logic using feathers' hook system implement before, after, and error hooks for each method allow for data validation, transformation, and business logic validators and resolvers validators ensure incoming data adheres to the schema definition resolvers allow adding or transforming data on objects going in and out of the backend provide a less verbose alternative to implementing certain functionality in hooks openapi configuration ( packages/server core/src/createapp ts ) set up the swagger ui and define global openapi settings configures the /openapi endpoint that serves the documentation openapi configuration the global openapi configuration is set up in packages/server core/src/createapp ts this is where you can configure the swagger ui and define global settings for your api documentation export const configureopenapi = () => (app application) => { app configure( swagger({ ui swagger swaggerui({ docspath '/openapi' }), specs { info { title 'infinite reality engine api surface', description 'apis for the infinite reality engine application', version packagejson version }, schemes \['https'], components { securityschemes { bearerauth { type 'http', scheme 'bearer' } } }, security \[{ bearerauth \[] }] }, idtype 'string', ignore { paths \['oauth', 'knex migrations'] } }) ) return app } for more information on configuring the openapi documentation, see the feathers swagger documentation on swaggeroptions https //feathersjs ecosystem github io/feathers swagger/#/api?id=swaggeroptions additional resources feathers swagger api documentation https //feathersjs ecosystem github io/feathers swagger/#/api complete reference for all available options openapi specification https //swagger io/specification/ the official openapi specification swagger ui https //swagger io/tools/swagger ui/ documentation on the swagger ui interface documenting endpoints docid 1jbo9mb4njisxg5a2p pa step by step guide for documenting api endpoints