Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/manudss/ngx-http-annotations


https://github.com/manudss/ngx-http-annotations

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

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

}



@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 = undefined): Observable {

    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 = 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 = undefined): Observable {

      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 {

    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