server codegen documentation #6265
Conversation
mario-guerra
requested review from
bterlson,
markcowl,
allenjzhang,
timotheeguerin,
witemple-msft,
chrisradek and
AlitzelMendez
as code owners
|
hi @josefree, I need your help with this codegen documentation, can you provide screenshots for the VS Code portions in the doc? |
|
No changes needing a change description found. |
|
You can try these changes here
|
|
There will be changes around how server scaffolding gets streamlined. @markcowl Let's keep this one open and see if Mark had any of his doc and then reconcile them. |
|
|
||
| ## Prerequisites | ||
|
|
||
| Before you begin, make sure you have the following installed: |
There was a problem hiding this comment.
with the introduction of the standalone cli feel like it might be better of to redirect the initial setup to the install doc
| Before you begin, make sure you have the following installed: | ||
|
|
||
| * **Node.js:** (version 20.x or later). Download from [https://nodejs.org/](https://nodejs.org/) | ||
| * **npm:** (version 6.x or later). Typically included with Node.js. |
There was a problem hiding this comment.
we say 7+ in the install docs
|
|
||
| * **Node.js:** (version 20.x or later). Download from [https://nodejs.org/](https://nodejs.org/) | ||
| * **npm:** (version 6.x or later). Typically included with Node.js. | ||
| * **TypeSpec compiler:** Install the latest `@next` version globally using: |
|
|
||
| 4. **Project structure:** After compiling, you will typically see the following structure: | ||
|
|
||
| ```text |
There was a problem hiding this comment.
See startlight filetree component to have a better presentation here https://starlight.astro.build/components/file-tree/, we use it in a few other places in the codebase too
There was a problem hiding this comment.
same for all the other dir examples
| @@ -0,0 +1,375 @@ | |||
| # Generating server stubs with TypeSpec: a user guide | |||
There was a problem hiding this comment.
Should this be reformulated as api first as this also mention clients
| ┃ ┃ ┃ ┣ ... (other operation interface files) | ||
| ``` | ||
|
|
||
| * **`Controllers`**: These folders contain *base classes* for your API controllers (e.g., `CommentOpsOperationsControllerBase.cs`, `TodoItemsOperationsControllerBase.cs`). These base classes define the API endpoints and handle basic request processing. **You will need to create concrete controller classes that inherit from these base classes and implement your business logic.** |
There was a problem hiding this comment.
This is out of date - there are no more base controllers
|
|
||
| * **`Controllers`**: These folders contain *base classes* for your API controllers (e.g., `CommentOpsOperationsControllerBase.cs`, `TodoItemsOperationsControllerBase.cs`). These base classes define the API endpoints and handle basic request processing. **You will need to create concrete controller classes that inherit from these base classes and implement your business logic.** | ||
|
|
||
| * **`lib`**: This directory contains utility classes such as custom attributes used for server side validation to ensure input data adhere to the spec. |
There was a problem hiding this comment.
| * **`lib`**: This directory contains utility classes such as custom attributes used for server side validation to ensure input data adhere to the spec. | |
| * **`lib`**: This directory contains helper classes used in generated code, such as custom attributes used for server-side validation to ensure input data adhere to the spec. |
|
|
||
| * **`Models`**: These files define the data models (also known as Data Transfer Objects or DTOs) used in your API (e.g., `TodoItem.cs`, `Project.cs`). These classes represent the structure of the data being exchanged between the client and the server. | ||
|
|
||
| * **`Operations`**: These files defines the service interface used for API operations. |
There was a problem hiding this comment.
| * **`Operations`**: These files defines the service interface used for API operations. | |
| * **`Operations`**: These files defines the service interface used for API operations. You will implement these interfaces to execute the business logic for each operation. |
|
|
||
| ## Cli: running the project and adding necessary code: | ||
|
|
||
| Now that you have the base controller, models and service interface generated, the next step is to implement the code with a service scaffolding and business logic for a runnable server. Please follow the instruction below: |
There was a problem hiding this comment.
This has changed quite a bit
There was a problem hiding this comment.
@markcowl where/how can I get the latest info on how it works?
| * `[Placeholder: Screenshot showing "Create TypeSpec Project" in the VSCode Explorer sidebar]` | ||
| * Select a project root folder. | ||
| * Provide the required inputs via Quick Picks, similar to using `tsp init` on the command line. | ||
|
|
| * Provide the required inputs via Quick Picks, similar to using `tsp init` on the command line. | ||
|
|
||
| 3. **Define your api:** Write your API specification in a `.tsp` file. | ||
|
|
There was a problem hiding this comment.
May mention “code faster with IntelliSense and Auto-completion support”. 
| 3. **Define your api:** Write your API specification in a `.tsp` file. | ||
|
|
||
| 4. **Generate the server stub:** | ||
| * Right-click on a `.tsp` file to open the context menu. |
There was a problem hiding this comment.
Better to introduce TypeSpec command here. Launch TypeSpec command with ">TypeSpec: Emit from TypeSpec" from Command Palette.
#6342 the gif is here. when it is merged. it can be used with ![vscode.gif] (https://raw.githubusercontent.com/microsoft/typespec/main/website/src/content/docs/docs/images/vscode_tsp_to_server_stubs_generation.gif)"
Putting this up for review only, do not commit. This is a draft and it still needs work.