Awesome
ngx-http-annotations
This library allows to interact with rest api in your angular app. It contains:
- Annotations for http methods (@GET, @POST, @PUT, @DELETE, @OPTIONS, @HEAD, @PATCH)
- Annotations for adding headers, setting produces results and intercepting response
- Params annotations
forked from : https://github.com/Mixalloff/ngx-http-rest
Installation
Install through npm:
$ npm install ngx-http-annotations --save
Development
Example of using library.
- Plug the HttpRestModule into your AppModule
import { NgxHttpAnnotationsModule } from 'ngx-http-annotations';
import { NgModule } from '@angular/core';
@NgModule({
imports: [
NgxHttpAnnotationsModule
]
})
export class AppModule {
}
- Create a service to work with rest api. Put annotations on the class, methods and params.
import { GET, POST, DELETE, Path, PathParam, Body, QueryParam, QueryParams, ResponseObservable } from 'ngx-http-annotations';
import { Injectable } from '@angular/core';
import RestConfig from 'app/core/configs/rest.config';
interface GoodsItem {
id: number,
name: string,
price: number,
sales?: boolean;
desc?: string;
children?: Array<GoodsItem>;
}
@Injectable()
@Headers({
'someHeader1': 'headerValue1',
'someHeader2': 'headerValue2'
})
@Path(`/test/goods`)
export class SomeRestService {
@GET
getGoods(@QueryParams /* Object with queryParams { [name: string]: [value: any] } */ queryObj?: any): any {}
@GET
getGoodsBySomeParam(@QueryParam('sales') /* ...?sales= */ isSold: boolean): any {}
@GET
@Path('/:id')
getGoodsItemById(@PathParam('id') itemId: number): any {}
@GET
@Path('/:id/child/:childId') /* Few path params */
getChildrenOfSomeGoods(@PathParam('id') id: number,
@PathParam('childId') childId: number
@QueryParam('sales') isSold: boolean,
@QueryParam('someParam') some: any): any {}
@POST
@Path('/create')
createGoods(@Body /* Body of POST request */ goodsObject: GoodsItem): any {}
@DELETE
@Path('/:id')
removeGoodsById(@PathParam('id') itemId: number): any {}
@GET
@Path('posts')
/**
* getPostForUserId(3, 2) : call the the url /posts?userId=2 and only take 3 results
*/
public getPostForUserId(number: number, @QueryParam('userId') userId: number, @ResponseObservable res: Observable<any> = undefined): Observable<any> {
return res.pipe(map((response) => response.slice(0, number)));
}
}
- Call the request method from component
import { Component, OnInit } from '@angular/core';
import { SomeRestService } from './some-rest.service';
@Component({
selector: 'some-test-component',
templateUrl: './test-component.component.html',
styleUrls: ['./test-component.component.css'],
providers: [SomeRestService]
})
export class TestComponent implements OnInit {
constructor(private someRestService: SomeRestService){}
ngOnInit() {
this.someRestService
.getGoods()
.subscribe( goods => console.log(goods) );
}
}
Description
Available annotations:
- Request methods @GET, @POST, @PUT, @DELETE, @OPTIONS, @HEAD, @PATCH - marks methods implementing the corresponding requests
- Added settings
- @Path - set path of url for request. Combined class @Path annotation value and current method @Path. Path params passed with ":". For example @Path('/someurl/:someParam')
- @Headers - set headers for request (if annotate class, then all class methods getting this headers. method Headers merge with class Headers)
- @Produces - setting expected response type. By default Reponse transformed by .json() method
- @Observes - setting http observes.
- Parameters
- @PathParam (or @Path) - pass current parameter by name to collected url. Example: someFunc(@PathParam('id') itemId: number) {}
- @Body - pass body object into request. Ex.: someMethod(@Body bodyObject: any){}
- @QueryParam - pass single query parameters into request. Ex.: someMethod(@QueryParam('a') a: any, @QueryParam('b') b: any) {}. someMethod(1, 2) -> ..requested_url..?a=1&b=2
- @QueryParams - pass object with few query params. Ex.: someMethod(@QueryParams queryObj: any){}. someMethod({x: 1, y: 2, z: 3}) -> ..requested_url..?x=1&y=2&z=3
- @ResponseObservable - specify in witch function params, the response observable will be added. Ex.: someMethod(@ResponseObservable res: Observable<any> = undefined){ /* transform request */ return res; }. need to initialise as undefined to pass compile error, and return a response.
Transform response with all rxjs function
By adding the parameters @ResponseObservable you can specify, where add the observable response,
@GET
@Path('posts')
/**
* getPostForUserId(3, 2) : call the the url /posts?userId=2 and only take 3 results
*/
public getPostForUserId(number: number, @QueryParam('userId') userId: number, @ResponseObservable res: Observable<any> = undefined): Observable<any> {
return res.pipe(map((response) => response.slice(0, number)));
}
Mocks calls
To have a feature to enable mocks api. When enabled, will call directly the function rather than call the http request.
To enable Mocks : in a module provider use this :
providers: [{ provide: HTTP_ANNOTATIONS_USE_MOCKS, useValue: true }]
You can specify a boolean value, or have a specific function, that will be used to know if the apps will use mock. This could help you to define mock only for specific call.
providers: [{ provide: HTTP_ANNOTATIONS_USE_MOCKS, useValue: (url, requestType, params, args): boolean => {
console.log('useMock : ', url, requestType, params, args);
return requestType === 'Get' ? true : false;
} }]
define your mocks by return a fake observable, with your mock data.
@GET
@Path('posts/:id')
public getPost(@PathParam('id') id: number): Observable<any> {
return of([{id: id, title: 'mock true'}]);
}
Change logs
0.6.x
-> updates to the latest versions of Angular -> Rename library to ngx-http-annotations -> add @ResponseObservable to transform response.
0.6.2 et 0.6.3
-> update to build the library with angular, to avoid error when build in --prod
0.7.x
-> Add a mock feature. -> Update dependency to latest
0.7.3 -> Add delay: Add a beta feature, to add a delay to all requests, or have a function that returns this delay. This could be useful, in the mock feature. By default, all mock, will have a default delay. But could be also added without mock, to simulate long request. -> Use all httpClient methods rather than use request method, use the corresponding method (get, put, delete ...). In order, to avoid issue with request method that throw a first empty error. -> Update dependencies: Update to version 13 of Angular.
0.8.0 -> Updates to Angular 16, and compile libs to ivy -> change to nx workspace -> Add unit tests
Source and issues
Code are located in github : https://github.com/manudss/ngx-http-annotations