Generate Code

To generate client code, server code, and/or documentation for a Facility Service Definition, do one of the following:

  • Use the Facility Editor. Enter an FSD or Swagger API definition, choose the desired generator, and click Download.
  • Run a command-line tool on the command line or in a build script.
  • Use one of the .NET libraries in your own .NET build tool.

Code Generators

Facility supports the following code generators:

  • C# (.NET): Generates C# code for clients and servers.
  • ASP.NET: Generates ASP.NET controllers for servers. Alternatively, use ASP.NET Core middleware: no code generation needed.
  • JavaScript/TypeScript: Generates a JavaScript or TypeScript API client.
  • Markdown: Generates Markdown documentation for your API.

The official Facility code generators conform to the following guidelines:

  • Encapsulate the protocol on the client. When a developer calls a service method using a generated client, the details of the protocol – the URL, GET vs. POST, whether the request fields are sent via query string or JSON body, which HTTP status codes are used, etc. – should be hidden from the caller, not because the details are secret, but because they are unrelated to the purpose of the call.
  • Encapsulate the protocol on the server. In the same way, code generated for a server implementation should provide a mechanism for the developer to implement each service method in such a way that the request fields are already extracted from the HTTP path, query string, JSON request body, etc., and in which the HTTP status code and JSON response fields are automatically determined from the response.
  • Adding methods or fields should not break clients. Previously generated clients should continue to work if methods or fields are added to an API. Existing code that calls a previously generated client should work with a newly generated client without modification.
  • Support asynchronous methods. Where possible, the client and server implementations should encourage asynchronous patterns.
  • Only generate files that change as the API definition changes. Code generators should not generate scaffolding that doesn’t change as service methods are added or modified. Scaffolding can be copied from an existing project or generated by a project template or Yeoman generator.
  • Delete previously generated files that are no longer needed. When it can be done safely, code generators should delete previously generated but now unneeded files.
  • Avoid merging changes into generated files. Developers should be discouraged from editing generated files, which should be replaced wholesale by code generators, not edited by them.
  • Keep it simple. Code generators should be as simple as possible, generating as little code as possible and supporting as few options as possible.

Swagger Tools

By converting your FSD to/from the Swagger (OpenAPI) 2.0 format, you can leverage the many Swagger tools and code generators. For example:

  • Swagger Editor makes it easy to generate client and server code from a Swagger definition.
  • Swagger Codegen supports dozens of languages and frameworks, including C++, Go, Java, Node, Objective-C, Python, Ruby, Swift, etc.
  • Swagger UI displays visual documentation for your API.
  • Many other open source and commercial tools also support Swagger.

Visual Studio Code Extension

The Facility API extension for Visual Studio Code provides syntax highlighting and error checking for FSD files.