ngx-http-annotations/README.md

This is a library to angular to use http request via decorator/annotations

# 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:

```sh
$ npm install ngx-http-annotations --save
```


### Development

Example of using library.

1) Plug the HttpRestModule into your AppModule

```typescript
import { NgxHttpAnnotationsModule } from 'ngx-http-annotations';
import { NgModule } from '@angular/core';

@NgModule({
  imports: [
    NgxHttpAnnotationsModule
  ]
})
export class AppModule {
}
```

2) Create a service to work with rest api. Put annotations on the class, methods and params.


```typescript
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)));
  }


}
```

3) Call the request method from component

```typescript
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:
1) Request methods
   @GET, @POST, @PUT, @DELETE, @OPTIONS, @HEAD, @PATCH - marks methods implementing the corresponding requests
2) 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.
3) 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,

  ```typescript
    
    @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 :
```typescript
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.


```typescript
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.

```typescript
  @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