> For the complete documentation index, see [llms.txt](https://easonwang.gitbook.io/web_advance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easonwang.gitbook.io/web_advance/api-ce-shi/swagger/zhu-jie-xie-zai-code-nei-sheng-cheng-swagger-ui.md).
# 註解寫在Code內生成swagger UI
## 註解寫在Code內生成swagger UI
### 安裝
```
yarn add swagger-jsdoc swagger-ui-express swagger-model-validator
```
### 使用
1. 新增： /router/swagger.js
```javascript
const express = require('express')
const router = express.Router()
const options = {
swaggerDefinition: {
info: {
title: 'REST - Swagger',
version: '1.0.0',
description: 'REST API with Swagger doc',
contact: {
email: ''
}
},
tags: [
{
name: 'AMSS5',
description: 'AMSS5 API'
}
],
schemes: ['http'],
host: 'localhost:3124',
basePath: '/api'
}, // 下面記得要寫上要讀哪邊的註解
apis: ['./router/grid.js', './router/project.js', './router/user.js', './database/schemas/grid.js']
}
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerUi = require('swagger-ui-express')
const swaggerSpec = swaggerJSDoc(options)
require('swagger-model-validator')(swaggerSpec)
router.get('/json', function (req, res) {
res.setHeader('Content-Type', 'application/json')
res.send(swaggerSpec)
})
router.use('/', swaggerUi.serve, swaggerUi.setup(swaggerSpec))
function validateModel (name, model) {
const responseValidation = swaggerSpec.validateModel(name, model, false, true)
if (!responseValidation.valid) {
console.error(responseValidation.errors)
throw new Error(`Model doesn't match Swagger contract`)
}
}
module.exports = router;
```
2.綁定swagger UI router
server.js
```javascript
const swaggerRoute = require("./router/swagger");
app.use("/swagger", swaggerRoute);
```
1. API 文件
```javascript
/**
* @swagger
* /:
* get:
* description: Create Grid
* tags:
* - Grid
* produces:
* - application/json
* responses:
* 200:
* description: stocks
* schema:
* $ref: '#/definitions/Stocks'
*/
或是
/**
* @swagger
* /:
* post:
* summary: Add a new pet
* parameters:
* - in: formData
* name: userId
*/
router.post('/', async (req, res) => {
.......
})
```
1. Model 文件
```javascript
/**
* @swagger
* definitions:
* Stock:
* type: object
* required:
* - id
* - name
* - currentPrice
* - lastUpdate
* properties:
* id:
* type: number
* name:
* type: string
* currentPrice:
* type: number
* lastUpdate:
* type: number
* Stocks:
* type: array
* items:
* $ref '#definitions/Stock'
*/
const GridSchema = new Schema({
......
})
```
5.瀏覽 swagger UI
[http://localhost:3000/swagger/api#/](http://localhost:3124/swagger/api#/)
> port 為你 server 的 port
參考至：
6.瀏覽產生出的swagger.json
> [https://localhost:3000/swagger/json](https://amss-5-portfolio.bridge5.asia/swagger/json)
## 加入Redoc
Redoc提供更完整的文件頁面
**使用方式**
在html加入如下
```markup
ReDoc
```
把上面的swagger.json替換為你的即可
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://easonwang.gitbook.io/web_advance/api-ce-shi/swagger/zhu-jie-xie-zai-code-nei-sheng-cheng-swagger-ui.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.