Swagger Code Generation

Help Requests
1

Hi all,

in my web api projects I’m using swagger as documentation platform. Now I’m evaluating how to use the documentation to generate Typescript-Aurelia-Code.
Until now I tested NSwagStudio and Swagger Codegen Cli. Unfortunatly both tools don’t work perfectly.

  1. NSwagStudio : It’s a good tool that is quite easy to handle. Each generated model has a constructor where I can create new models easily. But it seems that this tool ignores Jwt-Authorization totally. Is that true or do I miss here something?
  2. Swagger Codegen: Creates multiple files and handles the Authorization part (really cool). But here it seems that it uses aurelia-http-client instead of aurelia-fetch-client. Additionally it only creates interfaces of the models.

But overall I would like to ask the community if someone has expierence with the aurelia-code generation part and can give me some hints / best practices how to handle it?

following my approach how I currently try to handle it (example of the NSwagStudio):

  1. First I copy the generated sources into my project (src/api).
  2. Then I extend each model to add validation rules:
import {MyModel as DtoMyModel} from 'api/mygeneratedModel';

export class MyModel extends DtoMyModel{}

ValidationRules
   ...
   .On(MyModel);
  1. Then in my code (e.g. where I update mymodel)
...
this.MyModelClient.UpdateMyModel(this.myModel)
   .then(mymodel => {
        this.mymodel = new MyModel(mymodel); //this step is in case of NSwagStudio that the validation rules are get applied after the reload.
    });
...

In the stated example I handle the authorization manually using the aurelia-auth package. But I would appritiate it if the generated code (like swagger codegen) could take over that part… :confused:

2

Creates multiple files and handles the Authorization part (really cool). But here it seems that it uses aurelia-http-client instead of aurelia-fetch-client . Additionally it only creates interfaces of the model

I’m pretty confident it’s the other way around, or at least configurable. A part of my generated code:

/* tslint:disable */
//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v11.17.2.0 (NJsonSchema v9.10.45.0 (Newtonsoft.Json v9.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------
// ReSharper disable InconsistentNaming

import { inject } from 'aurelia-framework';
import { HttpClient, RequestInit } from 'aurelia-fetch-client';

About NSwagStudio, I don’t use it often though so I’m not sure. You can extend the service class and override a certain method to return the right class, no?

3

Many thanks for your answer (knowing that my question is quite ugly). Does your code refers to the Swagger-Codegen? I didn’t found any possibility to configure the aurelia-fetch-client.

Another point of the swagger-codegen that I don’t like is that methods expect “ParamObjects” as parameters instead of the required parameters itself. Really ugly :frowning:

async GetMyObjectById(params: IGetMyObjectParams) //Generated
async GetMyObjectById(id : number) //expected
4

Really ugly :frowning:

I found hand coding the server API makes it a bit beautiful :smile:

I don’t remember how to configure anymore, but I think you can only have ‘aurelia-fetch-client’ template?

5

Yeah, you’re totally right … so true :wink:

6

This is different, probably depends on framework. Here is what i got:

export interface SomeService {
    ...
    exportData(projectId: string, registrationId: number, latestOnly: boolean): Promise<ExportDataDto>;
    ...
}
7

mmh ok, this is quite unsetting :confused:

8

The default interfaces generated by NSwagStudio are dependent on the Swagger JSON file generated by the server-side API. For example, we use ServiceStack and that generates additional parameters that are meaningless in the API calls, so I override the JSON generation on the server, strip out the unwanted ‘query’ parameter that ServiceStack adds, remove the /Accept references, remove duplicates that cause name clashes in the TypeScript by adding the verb to the endpoint (_GET, _POST etc.), then use that.
It’s a bit of a pain, but once you have a suitable generation process it saves hours of manual manipulation in a development lifecycle.
I think in many cases you have to intercept or post-process the JSON structure before running through the Swagger codegen.
You could do the same thing by writing a custom codegen, but it’s all a bit messy.

2 Likes
9

Nswag allows generated client customisation. You can handle auth in those extensibility points

1 Like
10

OpenAPI Client Generators is a .NET Core command line program to generate strongly typed client API codes in C# on .NET Frameworks and .NET Core, and in TypeScript for Angular 5+, Aurelia, jQuery, AXIOS and Fetch API.

Since it is a .NET Core program, you may make a build for Linux or Mac.

1 Like
11

Please also check https://www.codeproject.com/Articles/5262184/OpenApiClientGen-to-Generate-Strongly-Typed-Client

2 Likes