My first OpenAPI integration

[Wouter Hendriks]

Logging my experience integrating an OpenAPI service, might be useful for others, as there is no documentation as of yet. Module name in example code is "sunfun".

Moduledefinition:

```

  <services>
    <openapiservice name="appservice" spec="openapi/sunfun.yaml" />

  </services>

  <backend>

    <openapi path="root:/.sunfun/openapi/appservice/" service="appservice" />

  </backend>

```

For my .yaml file, I copied the yaml from /webhare_testsuite/tests/system/nodejs/test_generated_files.ts

But any example will do, ie https://editor-next.swagger.io/ (menu File => Load Example)

Endpoint derived from <backend><openapi></backend>, eg:

http://localhost:8000/.sunfun/openapi/appservice/

This page (at the moment) shows some useful URLs to the Swagger UI and spec.

Created a test file "test_openapi.ts" to test basic functionality which basically amounts to:

```

run();

async function run() {
  const userlistcall = await fetch('http://localhost:8000/.sunfun/openapi/appservice/activities', {});
  console.log(await userlistcall.json());
}

```

Can be run with `wh run mod::sunfun/scripts/test/test_openapi.ts`, just like whscr files.

Problems / takeaways:

1) kept running into `Internal error - enable the 'etr' debug flag to enable full error tracing`, no idea how to set that flag in my test file (a simple ?wh-debug=etr didn't work, would've been nice). Tried from WHLIB using GetSignedWHDebugOptions, also didn't work.

@WebHare any solution for this?

2) If you're getting this error:

```

error: 'Validation of the response (code 200) for "get /activities" returned error: must NOT have additional properties (additionalProperty="description") (at "/0")',

```

Then check your .yaml file, it's probably different from your API response.

3) CORS issues, added the same path as <openapi> in a <webrule> in <backend>:

    <openapi path="root:/.sunfun/openapi/appservice/" service="appservice" />
    <webrule path="root:/.sunfun/openapi/appservice/" match="initial" >
      <addheader header="Access-Control-Allow-Origin" value="*"/>
    </webrule>

@WebHare, it works, but is this the proper way? If so, wouldn't it be better to be able to add <addheader> into <openapi>?

4) Added integer as param, needed to use number:

```

      parameters:
        - name: id
          in: path
          description: ID of activity to return
          required: true
          schema:
            type: integer

```

=>

...

          schema:
            type: number

```

@WebHare: maybe support integer? Both 32 and 64 bits? https://swagger.io/specification/#data-types

All in all, seems to work nicely already!

[Arnold Hendriks]

Thanks for the writeup - someone should probalby update the examples at https://www.webhare.dev/manuals/typescript/openapi/ at one point

 

4) Added integer as param, needed to use number:

```

      parameters:
        - name: id
          in: path
          description: ID of activity to return
          required: true
          schema:
            type: integer

```

=>

...

          schema:
            type: number

```

@WebHare: maybe support integer? Both 32 and 64 bits? https://swagger.io/specification/#data-types

They don't really map to nice types in JS. int32 doesn't really exist and BigInt is no fun to work with, so I'm not sure what the use would be

 

[Wouter Hendriks]

Yeah, didn't know about https://www.webhare.dev/manuals/typescript/openapi/ before playing with it :-)

> They don't really map to nice types in JS. int32 doesn't really exist and BigInt is no fun to work with, so I'm not sure what the use would be

True, it's just that the spec supports it, so you would expect it to work I guess? It's too naive to think "just map them to INTEGER and INTEGER64, and be done with it"?

Op vrijdag 17 november 2023 om 16:01:51 UTC+1 schreef Arnold Hendriks: