Skip to content

Open API to Client Codes

Jump to bottom
fonlow edited this page Mar 11, 2020 · 9 revisions

(Under construction, in development)

Open API (Swagger) is designed for RESTful Web API, neutral to operation platforms and development platforms, generating codes for both servers and clients.

WebApiClientGen is designed for RPC Web API, optimizing the capacity and the abilities of ASP.NET, C# and TypeScript, generating codes for clients only.

Open API supports while WebAPI doesn't

  • Server side codes.
  • Describe multiple responses of an operation, while WebApiClientGen supports only the response with status code 200 or 204.
  • Handle HTTP header and cookie as parameter
  • Handle authentication

Web API supports while Open API doesn't

  • Namespaces.
  • Generic

The overlapping areas:

  1. Strongly typed API.
  2. Client side data models.

Design Preferences

  • Headers and cookie manipulations are often for authentication. Such manipulations could be done through intercept.
  • REST could be considered as technical details at the transportation layer, while RPC may provide higher abstraction of business logic.

This is one of the reasons why OpenApiToClientCodes could generate cleaner and simpler client codes within the business scope of specific client programming.

In Open API, there are some features not friendly to strongly typed languages like C# but to JavasScript:

  1. Discriminator Object with oneOf, anyOf, allOff. The best match could be object, rather than picking one. Or translate this into tuple

In what scenarios you should not use OpenApiToClientCodes

  • The Open API definitions use header for data payload.
  • Use arbitrary url paths without consistent patterns.
  • Request body of POST and Put uses content media types other than text/plain and application/json. For Example, application/x-www-form-urlencoded.
  • Swagger 1.0, 2.0

What not supported

  1. Post form data.
  2. Post stream data for upload

Roadmap

  1. Better handling of allOf, anyOf and oneOff, in TS and C#.
  2. Optionally define one namespace for data models and the other for functions.
  3. Some property constraints may become doc comments.
Clone this wiki locally