guide: framework flask

Author: philsturgeon

openapi/frameworks/flask.mdx

@@ -7,9 +7,9 @@ import { Callout } from "@/mdx/components";
 
 # How to generate an OpenAPI document with Flask
 
-When building REST APIs with Flask, clear and accurate documentation helps API consumers integrate quickly and confidently. [The OpenAPI Specification](https://swagger.io/specification/) has become the industry standard for documenting RESTful APIs, but writing and maintaining OpenAPI documents by hand is tedious and error-prone.
+When building REST APIs with Flask, clear and accurate documentation helps API consumers integrate quickly and confidently. [The OpenAPI Specification](https://spec.openapis.org/oas/latest.html) has become the industry standard for documenting RESTful APIs, but writing and maintaining OpenAPI documents by hand is tedious and error-prone.
 
-`flask-smorest` solves this by generating OpenAPI documentation directly from Flask code, using decorators and marshmallow schemas already in use. This guide covers generating an OpenAPI document from a Flask project and using it to create SDKs with Speakeasy, covering the following:
+The `flask-smorest` extension solves this by generating OpenAPI documentation directly from Flask code, using decorators and marshmallow schemas already in use. This guide covers generating an OpenAPI document from a Flask project and using it to create SDKs with Speakeasy, covering the following:
 
 - Setting up a Flask REST API with `flask-smorest`
 - Integrating OpenAPI document generation
@@ -30,7 +30,7 @@ The two main decorators are:
 - **`@blp.response(status_code, schema)`**: Specifies the response code and marshmallow schema for a method. flask-smorest uses this to document the response and serialize the return value.
 - **`@blp.arguments(schema)`**: Validates and deserializes the request body against a marshmallow schema, and documents the expected request body in the OpenAPI spec.
 
-## Example API repository
+## Sample API code
 
 <Callout title="Example repository" type="info">
 The source code for the completed example is available in the [**Speakeasy examples repository**](https://github.com/speakeasy-api/examples.git) (framework-flask).
@@ -49,7 +49,7 @@ For this guide, we'll use a simple Formula 1 (F1) lap times API with the followi
 To follow this guide:
 
 - Python 3.8 or higher
-- An existing Flask project or a copy of the provided [example repository](https://github.com/speakeasy-api/flask-openapi-example)
+- An existing Flask project or a copy of the provided [example repository](https://github.com/speakeasy-api/examples/tree/main/framework-flask)
 - A basic understanding of Flask and REST APIs
 
 ## Setting up flask-smorest
@@ -360,7 +360,7 @@ info:
   version: v1
 openapi: 3.1.0
 paths:
-  /circuits/:
+  /circuits:
     get:
       responses:
         '200':
@@ -397,7 +397,7 @@ paths:
       summary: Create a new circuit
       tags:
       - Circuits
-  /circuits/{circuit_id}:
+  /circuits{circuit_id}:
     delete:
       responses:
         default:
@@ -446,7 +446,7 @@ paths:
       summary: Update an existing circuit
       tags:
       - Circuits
-  /drivers/:
+  /drivers:
     get:
       responses:
         '200':
@@ -532,7 +532,7 @@ paths:
       summary: Update an existing driver
       tags:
       - Drivers
-  /lap-times/:
+  /lap-times:
     get:
       responses:
         '200':
@@ -709,10 +709,10 @@ Use `@blp.response()` to specify the expected response code and schema for a met
         return Circuit.query.all()
 ```
 
-This generates the following entry for the `/circuits/` `GET` operation in the OpenAPI document:
+This generates the following entry for the `GET /circuits` operation in the OpenAPI document:
 
 ```yaml filename="openapi.yaml"
-  /circuits/:
+  /circuits:
     get:
       responses:
         '200':