{"id":31966,"date":"2024-03-26T14:27:17","date_gmt":"2024-03-26T13:27:17","guid":{"rendered":"https:\/\/www.dbi-services.com\/blog\/?p=31966"},"modified":"2024-09-02T09:23:49","modified_gmt":"2024-09-02T07:23:49","slug":"add-a-ui-to-explore-the-feathers-js-api","status":"publish","type":"post","link":"https:\/\/www.dbi-services.com\/blog\/add-a-ui-to-explore-the-feathers-js-api\/","title":{"rendered":"Add a UI to explore the Feathers.js API"},"content":{"rendered":"\n

Following on from my previous article: Create REST API from your database in minute with Feathers.js<\/a>, today I want to add a UI to explore the Feathers.js API.<\/p>\n\n\n\n

When we provide an API, it’s common to make a tool available to explore the exposed methods.
Swagger UI<\/a> is one such tool, and fortunately, in the Feathers.js ecosystem, a package<\/a> is available for this purpose.<\/p>\n\n\n\n

<\/p>\n\n\n\n

First step: install and declare the package<\/h2>\n\n\n\n

In my previous article, I created a Feathers.js project using Koa as HTTP framework, TypeScript as language and NPM as package manager. To install the feathers-swagger<\/a> package, I use the command :<\/p>\n\n\n\n

npm install feathers-swagger swagger-ui-dist koa-mount koa-static<\/code><\/pre>\n\n\n\n
Once I’ve installed the necessary packages, I just need to declare the Swagger interface in my project.<\/p>\n\n\n\n
At the beginning of the src\/app.ts file, I add the swagger package import:<\/p>\n\n\n\n
import swagger from 'feathers-swagger';\n<\/code><\/pre>\n\n\n\n
Then, before<\/strong> the “app.configure(services)”, I add the Swagger declaration:<\/p>\n\n\n\n
app.configure(swagger({\n  specs: {\n    info: {\n      title: 'Workshop API ',\n      description: 'Workshop API rest services',\n      version: '1.0.0',\n    }\n  },\n  ui: swagger.swaggerUI({ docsPath: '\/docs' }),\n}))<\/code><\/pre>\n\n\n\n
Note: <\/strong>the position of the declaration in the file is very important: if it’s after the services configuration, the Swagger interface will be empty.<\/p>\n\n\n\n
Second step: expose the service in Swagger UI<\/h2>\n\n\n\n
Once the feathers-swagger package has been installed and initialized in the project, all I have to do is tell the services what to expose. To do this, I add a docs part to my service workshop service in the file (src\/services\/workshop\/workshop.ts).<\/p>\n\n\n\n
\n\/\/ A configure function that registers the service and its hooks via `app.configure`\nexport const workshop = (app: Application) => {\n  \/\/ Register our service on the Feathers application\n  app.use(workshopPath, new WorkshopService(getOptions(app)), {\n    \/\/ A list of all methods this service exposes externally\n    methods: workshopMethods,\n    \/\/ You can add additional custom events to be sent to clients here\n    events: [],\n    docs: createSwaggerServiceOptions({\n      schemas: { workshopSchema, workshopDataSchema, workshopPatchSchema, workshopQuerySchema },\n      docs: {\n          \/\/ any options for service.docs can be added here\n          description: 'Workshop service',\n      }\n    }),\n  })<\/code><\/pre>\n\n\n\n
Don’t forget to add the necessary imports at the beginning of the file:<\/p>\n\n\n\n
import {\n  workshopDataValidator,\n  workshopPatchValidator,\n  workshopQueryValidator,\n  workshopResolver,\n  workshopExternalResolver,\n  workshopDataResolver,\n  workshopPatchResolver,\n  workshopQueryResolver,\n  workshopDataSchema,\n  workshopPatchSchema,\n  workshopQuerySchema,\n  workshopSchema\n} from '.\/workshop.schema'\n\nimport type { Application } from '..\/..\/declarations'\nimport { WorkshopService, getOptions } from '.\/workshop.class'\nimport { workshopPath, workshopMethods } from '.\/workshop.shared'\nimport { createSwaggerServiceOptions } from 'feathers-swagger'<\/code><\/pre>\n\n\n\n
Important<\/strong> : in the case of a TypeScript project, the docs property is not recognized. An additional type declaration must therefore be added. In the src\/declarations.ts file, add :<\/p>\n\n\n\n
declare module '@feathersjs\/feathers' {\n  interface ServiceOptions {\n    docs?: ServiceSwaggerOptions;\n  }\n}<\/code><\/pre>\n\n\n\n
Testing the UI<\/h2>\n\n\n\n
As usual, to test the service, I use the command :<\/p>\n\n\n\n
npm run dev<\/code><\/pre>\n\n\n\n
Once the server has been started, simply access the docs page: http:\/\/localhost:3030\/docs\/<\/p>\n\n\n\n
\"Swagger<\/figure>\n\n\n\n
From the Swagger interface, I can test API methods:<\/p>\n\n\n\n
\"Swagger<\/figure>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
Adding a UI to explore the Feathers.js API is quick and easy, thanks to our ecosystem packages.<\/p>\n\n\n\n
Swagger UI is a very useful tool, and adding it to your project is a good idea in many cases, such as :<\/p>\n\n\n\n