OpenAPI SpecificationServer Frameworks

FastAPI Instrumentation

FastAPI is a popular Python web framework developed by tiangolo.

The offering brands itself as

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python based on standard Python type hints.

FastAPI plays very nicely with Fern because it has the power to output OpenAPI specs! Below we’ll outline some tips for generating a rich OpenAPI with FastAPI.

OpenAPI generation

By default, FastAPI will generate an OpenAPI spec for you based on your routes and your data models! You can access this spec by visiting /docs on your FastAPI server.

If you are not seeing any OpenAPI spec (or the Swagger UI), you may need to review your FastAPI server configuration as the path may have been changed, or completely omitted.

1 from fastapi import FastAPI
2 
3 ...
4 
5 FastAPI(
6     openapi_url="/openapi.json",  # <-- this is the file and URL needed to access the OpenAPI spec, `docs_url` and `redoc_url` are convenient wrappers that display the file in a UI!
7     docs_url="/docs",             # <-- this is the URL to access the Swagger UI, which will point to your OpenAPI spec
8     redoc_url="/redoc"            # <-- this is the URL to access the ReDoc UI, which will point to your OpenAPI spec
9 )

Specifying servers

Fern will automatically generate clients that point to the servers you configure within your OpenAPI spec, so it’s important to specify the servers that your API will be hosted on.

1 from fastapi import FastAPI
2 
3 ...
4 
5 app = FastAPI(servers=[{"url": "http://prod.test.com", "description": "Production server"}])
6 # This creates the following server object in your OpenAPI spec:
7 # "servers":[{"url":"http://prod.test.com","description":"Production server"}],

OpenAPI extensions

FastAPI allows you to add in extra OpenAPI configuration directly within your route, through the use of the openapi_extra parameter. Below, we’ve annotated a “good” route within FastAPI that has it’s typings as well as Fern extensions to assist in naming.

1 @router.post(
2     "/your/post/endpoint",
3     response_model=YourResponseModel,            #  <-- with FastAPI, it is important to specify your response model so that it comes through to the OpenAPI spec
4     summary="Get some response for your req",    #  <-- if you'd like to add a description to your endpoint, you can do so here
5     openapi_extra={                              #  <-- finally, you can add in your Fern extensions here, these extensions will produce SDK code that looks something like: `client.endpoints.create(...)` in python
6         "x-fern-sdk-method-name": "create",
7         "x-fern-sdk-group-name": "endpoints",
8         "x-fern-availability": "beta",
9     },
10 )
11 async def your_post_endpoint(
12     payload: YourRequestModel,
13 ) -> YourResponseModel:

Specifying examples

FastAPI allows you to specify examples for your data models, which Fern will pick up and use within your generated SDKs and documentation automatically.

For more information on leveraging examples within Fern, please refer to the Fern documentation.

For more information on this FastAPI functionality, please refer to the FastAPI documentation.

1 from pydantic import BaseModel
2 
3 class MyObject(BaseModel):
4     id: str
5 
6     class Config:
7         schema_extra = {
8             "example": {
9                 "id": "a-cool-uuid",
10             }
11         }

Additional customization

FastAPI has a lot of flexibility in how you can customize your OpenAPI spec. Please refer to the FastAPI documentation for more information.

1	from fastapi import FastAPI
2
3	...
4
5	FastAPI(
6	openapi_url="/openapi.json", # <-- this is the file and URL needed to access the OpenAPI spec, `docs_url` and `redoc_url` are convenient wrappers that display the file in a UI!
7	docs_url="/docs", # <-- this is the URL to access the Swagger UI, which will point to your OpenAPI spec
8	redoc_url="/redoc" # <-- this is the URL to access the ReDoc UI, which will point to your OpenAPI spec
9	)

1	from fastapi import FastAPI
2
3	...
4
5	app = FastAPI(servers=[{"url": "http://prod.test.com", "description": "Production server"}])
6	# This creates the following server object in your OpenAPI spec:
7	# "servers":[{"url":"http://prod.test.com","description":"Production server"}],

1	@router.post(
2	"/your/post/endpoint",
3	response_model=YourResponseModel, # <-- with FastAPI, it is important to specify your response model so that it comes through to the OpenAPI spec
4	summary="Get some response for your req", # <-- if you'd like to add a description to your endpoint, you can do so here
5	openapi_extra={ # <-- finally, you can add in your Fern extensions here, these extensions will produce SDK code that looks something like: `client.endpoints.create(...)` in python
6	"x-fern-sdk-method-name": "create",
7	"x-fern-sdk-group-name": "endpoints",
8	"x-fern-availability": "beta",
9	},
10	)
11	async def your_post_endpoint(
12	payload: YourRequestModel,
13	) -> YourResponseModel:

1	from pydantic import BaseModel
2
3	class MyObject(BaseModel):
4	id: str
5
6	class Config:
7	schema_extra = {
8	"example": {
9	"id": "a-cool-uuid",
10	}
11	}