# {"$schema":"http://localhost:65000/schemas/ResponseBodyBody.json","message":"Hello John"}
```

Browse to http://localhost:65000/docs#/operations/post-hello to see the generated schema in a Swagger-like viewer.

![Huma OpenAPI documentation](/assets/openapi/guide/huma.png)

## Using an OpenAPI meta-framework

The final option is to manually rewrite your server router in a meta-framework, and use that framework to generate a schema and new server code. For Go, this framework is called Goa. Speakeasy has an article demonstrating the process [here](/openapi/frameworks/goa).

In brief, the code you'll write is Go, but it is neither normal server code nor OpenAPI in YAML. It looks like the Go description of a schema below.

```go
var _ = Service("order", func() {
	Description("A waiter that brings drinks.")
	Method("tea", func() {
		Description("Order a cup of tea.")
		Payload(func() {
			Field(1, "isGreen", Boolean, "Whether to have green tea instead of normal.")
			Field(2, "numberSugars", Int, "Number of spoons of sugar.")
			Field(3, "includeMilk", Boolean, "Whether to have milk.")
		})
		Result(String)
		HTTP(func() {
			Meta("openapi:tag:Drink operations")
			POST("/tea")
		})
		GRPC(func() {
		})
	})
	Files("/openapi.json", "./gen/http/openapi.json")
})
```

Using an OpenAPI meta-framework to generate a schema is highly dependent on the programming language you use, as most languages don't have tools like Goa available (see the list of tools in the next section). A meta-framework is a great tool for maintaining server code separately from your schema (unlike using annotations), with the added advantage that it allows business analysts to understand and edit API contracts without needing to know a programming language in detail. It also makes the code to be maintained isolated and small, compared to annotating your entire server codebase.

The disadvantage of this approach is that you will be heavily dependent on the framework you choose, and that it's regularly maintained to fix bugs in generation and stay current with changes to OpenAPI. You will also be choosing a tool that's built on top of another tool. It might be easier for your team to stick with a popular web framework and simple OpenAPI annotations. Evaluate the framework you are considering and the quality of its outputs in a short test to decide if you like this approach.

## Tools available in each language

Now that you have seen the options you can choose from to generate an OpenAPI schema, you need to see if the tools you need are available for your language. In this final section, we list all the best tools we have found, ignoring repositories that haven't been updated in a year.

### C#, F#, and .NET

The .NET framework has two libraries you can use to generate OpenAPI schemas: [OpenAPI.NET](https://github.com/microsoft/openapi.net) and [NSwag](https://github.com/ricosuter/nswag).

Microsoft has official tutorials on both:

- [Generate OpenAPI documents with the `Microsoft.AspNetCore.OpenApi` package](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-8.0&tabs=visual-studio%2Cminimal-apis)
- [Get started with NSwag and ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-8.0&tabs=visual-studio)

The `AspNetCore.OpenApi` package allows you to add attributes to your code. NSwag can generate client and server code, too.

### Go

[go-swagger3](https://github.com/parvez3019/go-swagger3) creates OpenAPI schemas for Go code based on text comments.

[Huma](https://huma.rocks) is a combination of annotations and an OpenAPI-aware framework that allows you to add attributes to your API to generate a schema and serve documentation for it.

[Fuego](https://go-fuego.github.io/fuego/docs/guides/openapi) is an OpenAPI-aware web framework. The [`swaggest/rest`](https://github.com/swaggest/rest) package, based on the Chi web framework, and [GoAPI](https://github.com/hvuhsg/goapi) offer similar functionality.

[Goa](https://github.com/goadesign/goa?tab=readme-ov-file) is a meta-framework that allows you to write an API design in Go code, which it then compiles into web server code and an OpenAPI schema.

[ogen](https://ogen.dev/docs/intro) generates data types and server and client code from an OpenAPI schema, but not an OpenAPI schema.

### JavaScript

JavaScript does not have static typing, but you can add type hints in text comments using [JSDoc](https://jsdoc.app/about-getting-started).

[swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc) will convert your JSDoc annotations to an OpenAPI schema.

[hapi-swagger](https://github.com/hapi-swagger/hapi-swagger) adds OpenAPI features to the hapi web framework by using JSON descriptions of routes.

### TypeScript

[Tsoa](https://tsoa-community.github.io/docs/getting-started.html#configuring-tsoa-and-typescript) is similar to Goa — a meta-framework in TypeScript that will output server code and an OpenAPI schema.

[swagger-docs](https://github.com/AmishFaldu/swagger-docs/wiki/Getting-Started) creates an OpenAPI schema for you from TypeScript attributes.

### PHP

[OpenAPI PHP Attributes Generator](https://github.com/uderline/openapi-php-attributes) is a code-first tool that generates an OpenAPI schema from annotations.

[Swagger-PHP](https://zircote.github.io/swagger-php/) generates an OpenAPI schema from code attributes or comment annotations.

If you're using Laravel, you can use [Scramble](https://scramble.dedoc.co) to generate an OpenAPI schema without needing to add annotations. [Scribe](https://scribe.knuckles.wtf) is similar.

[API Platform](https://api-platform.com/), which works with Laravel and Symfony, provides OpenAPI features using your existing code, extended by attributes.

[PSX](https://phpsx.org/docs/intro) is an OpenAPI-aware web framework.

### Python

[drf-spectacular](https://drf-spectacular.readthedocs.io/en/latest/readme.html) automatically generates an OpenAPI schema from your Django code. You can add more information to your code with the `@extend_schema` attribute.

[FastAPI](https://fastapi.tiangolo.com) is an OpenAPI-aware web framework.

### Rust

[Poem](https://docs.rs/poem-openapi/latest/poem_openapi/) is the only Rust web framework that is OpenAPI-aware. Poem automatically generates an OpenAPI schema for you and serves it through the Swagger UI at your site `/docs`.

The three most popular web frameworks, axum, Actix Web, and Rocket, don't support OpenAPI yet, though they are working on it. For these, you should add OpenAPI attribute annotations with [utoipa](https://github.com/juhaku/utoipa). The Axum team has been working to elegantly integrate with utoipa. Take a look at an example [here](https://github.com/juhaku/utoipa/blob/master/examples/axum-utoipa-bindings/src/main.rs).

### Java

For frameworks that support the Jakarta RESTful Web Services specification (JAX-RS), formerly Java API for RESTful Web Services, you can use [Swagger Core](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started) to automatically generate an OpenAPI schema from code annotations.

[Swagger Parser](https://github.com/swagger-api/swagger-parser) will generate Java objects when given an OpenAPI schema. [guardrail](https://github.com/guardrail-dev/guardrail) will generate server code for you from your OpenAPI schema and supports Spring and Dropwizard. [openapi-processor](https://openapiprocessor.io/oap/home.html) will generate Java objects and server code interfaces in Spring or Micronaut, given an OpenAPI schema.

### Scala

If you're working in Scala, you can use the tools described in the Java section or the Scala-specific tools described below.

[endpoints4s](https://endpoints4s.github.io/quick-start.html) is a meta-framework that describes your API in code. You reference this code as a shared project in your client and server code, then implement the functions the API description specifies. endpoints4s will also generate an OpenAPI schema for you. Note that endpoints4s will not generate any code for you.

[SBT OpenApi Schema Codegen](https://github.com/eikek/sbt-openapi-schema) will generate the `/components/schema` types from your OpenAPI schema in Scala.

[Guardrail](https://github.com/guardrail-dev/guardrail) is a schema-first tool that will generate server code for you from your OpenAPI schema. It supports Akka, Dropwizard, and http4s.

### Kotlin

[Fabrikt](https://github.com/cjbooms/fabrikt) is a schema-first tool that generates data classes and interfaces for server and client code.

## The schema-first workflow

The alternative to a code-first approach is schema-first. If you treat your OpenAPI schema as your principal source after writing it or generating it from your code, and generate server code from it thereafter, then your code and schema will always be synchronized. While this approach is similar to the meta-framework approach, it provides a schema that's easier to read for non-programmers, though it may not be able to generate the framework's more specific features. A schema-first approach also allows you to add detailed text descriptions to help clients understand what your service endpoint does, which you may not be able to do in code.

Generating server code doesn't mean that you have to overwrite your existing code. You can use the generated code merely as an interface, or contract, to call your underlying code and check that all its requests and responses are of the expected types.

## Further reading

While there are a few tools listed above that do more than generate a schema from code, there are hundreds of OpenAPI tools and services available. Tools that validate code against schemas, create contracts, generate server code from a schema, and create and run tests. To see what's available, visit:

- https://tools.openapis.org/categories/all.html