Generating API documentation?

[bduffany]

Does Next.js have a convenient way to generate documentation for /api routes? Or are there external tools which would make it easy to generate documentation?

[Jay-study-nildana]

I am looking for the exact same answer. is next.js not supposed to be used for building api servers?

There are threads about generating API documentation but none of them have answers or responses :(

[Jay-study-nildana]

Okay, I did some homework, and I think I found out the answer.

The background for my question is that, I am a ASP.NET API developer. In ASP.NET (standard, core, version 5), have built in systems to automatically generate API documentation. Further, generating swagger documentation is as simple as plugging a swagger nugget package and we are good to go. It's easy and convenient and so on.

After spending hours and hours growing through different documentations of different frameworks (Next.JS, Node JS, Express JS), and so many stack overflow and so many reference books from my digital library subscription, I have realised that, a system (like in .NET) to automatically generate API documentation simply does not exist.

Which explains why there is no content related to it. From what I understand, we have to build out our own API documentation using Swagger specification, and then, use Swagger documentation generator to generate the API documentation. There are some tools which will help in writing the swagger specification, but ultimately, it has to be done by hand, manually.

For a moment there, I thought, Postman might help. Postman does not currently have a option to export in Swagger Spec.

There are (paid) services that allow Postman stuff to be exported to Swagger Spec.

Ultimately, it comes down to who and how the swagger spec file gets created. Once the documentation is ready in Swagger Spec, the actual documentation generation itself is automatic.

Hopefully, this will help others who come looking (perhaps from .NET) for something similar.

Of course, if I am wrong, that would be a relief, and please correct my views above.

[bduffany]

I wonder how hard it'd be to write a script that traverses all the files under pages/api and parses an exported metadata variable with a well-known name (e.g. docs), and generate a swagger spec automatically, like this:

export const docs = {
  methods: {
    'GET': 'Returns items from the shopping cart.',
    'POST': 'Adds items to the shopping cart.',
  },
  params: [
    { name: 'cartId', type: 'path', help: 'Shopping cart ID' },
    { name: 'productId', type: 'query', help: 'Product to add to the cart', methods: ['POST'], },
    { name: 'quantity', type: 'query', help: 'Quantity of the product to add', methods: ['POST'], default: 1 }, 
    docs_common.AUTH_HEADER, // can even import parts of docs from other modules!
  ]
}

The tool would do something like

for (const path of traverse('pages/api', { extensions: ['.js', '.ts'] })) {
  const routeModule = require(path);
  if (routeModule.docs) addToSwaggerSpec(path, routeModule.docs);
}

[Jay-study-nildana]

@bduffany

I will give this a spin when I work on Next.JS. I have since moved on to Strapi for API development, so hopefully, this will work there too. I have come to understand that Next is primarily related to server side apps and services, and API development is not exactly its main forte.

[note 1 : I have no idea how to write the stuff that you just wrote. as detailed above, I was expecting, some kind of plug n play, similar what I have experienced in .NET. I dont know if you have any experience in .NET. You literally get the API documentation with zero effort on your part]

[note 2 : "I wonder how hard it'd be to write a script". My thoughts exactly. Why is not included in, or perhaps, in the example folder. Like I said, I am new]

[parlay96]

@bduffany I used a script to traverse the entire pages page. Generate a router
"create-router": "node create-file-router.js",
// create-file-router.js
`var fs = require("fs")
/*解析需要遍历的文件夹/
var path = require("path")
var readline = require('readline')
var render = require('json-templater/string')
var endOfLine = require('os').EOL // 换行

var filePath = path.resolve("./src/pages")
var filterFileName = ['components', 'models', 'api', 'style', 'utils'] // 排除文件目录
// pages文件下面，哪些文件名需要作为页面，则会在自动生成路由的时候去匹配它，非下面的文件名，不会被访问到
var targetFileName = ['index.tsx', 'example.tsx']
var OUTPUT_PATH = './config/yp-router.js'

/**文件遍历方法(找出所有匹配的路径页面) */
function fileDisplay() {
let routerPath = []
function readFileList (dir) {
let files = fs.readdirSync(dir)
// 删除page下面的api文件
files = files.filter(item => item.indexOf('api') == -1)
// 遍历读取到的文件列表
files.forEach(filename => {
const fullPath = path.join(dir, filename)
// 根据文件路径获取文件信息
const stats = fs.statSync(fullPath);
const isFile = stats.isFile() //是文件
const isDir = stats.isDirectory() //是文件夹
// 需要读取文件内容（也就是页面）
if (isFile && targetFileName.indexOf(filename) != -1) {
routerPath.push(fullPath)
}
if (isDir && filterFileName.indexOf(filename) == -1) {
readFileList(fullPath) //递归读取文件
}
})
}
readFileList(filePath)
return routerPath
}

/*找出所有的路由对应关系key：val/
const queryRouterPath = () => {
const routerPath = fileDisplay() // 需要匹配的路径表
return new Promise((resolve, reject) => {
let routerData = [] // 路由表
let numc = 0
routerPath.forEach((fullPath, index) => {
// 根据路径读取文件内容
read_file(fullPath,function (data) {
numc = numc + 1
// 取出内容部分的后面50行代码
let contentData = data.slice(data.length - 50, data.length)
// console.log(contentData)
// 遍历找出页面导出的内容信息
contentData.forEach(item => {
// 表示当前页面存在重定路径
if (item.indexOf('redirectTargetUrl') != -1) {
// console.log(item)
// 解析导出来的页面路径配置对象
let splitData = item.split('=')
let dar = splitData[1].replace(/\s+/g, '')
// 这种方式字符串对象key必须加引号，不可取！
// let pathObj = JSON.parse(dar)
// 字符串转对象
let pathObj = eval('(' + dar + ')')
// console.log(pathObj)

                  // 获取当前页面的客户端路径
                  // console.log(fullPath, filePath)
                  let sLit = fullPath.split(filePath)[1]
                  // console.log(sLit)
                  let pLit = sLit.replace(/\\/g, "/")
                  // console.log(pLit)
                  // 剪去.tsx，因为路径后面不需要这个
                  let kLit = pLit.split('.tsx')
                  // 剪去/index，因为路径后面不需要这个
                  let fLit = kLit[0].split('/index')
                  // console.log(kLit, fLit)
                  // clientPath代表是客户端路由的访问地址，也是page下面的文件对应关系！
                  routerData.push({
                    ...pathObj,
                    clientPath: fLit[0]
                  })
              }
          })
          // 如果是最后一个文件了，直接返回
          if (numc == routerPath.length) {
            resolve(routerData)
          }
        })
    })
})

}

/*定义读取文件内容方法/
function read_file(path,callback){
var fRead = fs.createReadStream(path);
var objReadline = readline.createInterface({
input:fRead
})
var arr = new Array()
objReadline.on('line',function (line) {
arr.push(line)
})
objReadline.on('close',function () {
callback(arr)
})
}

/生成路由文件/
queryRouterPath().then(data => {
// console.log(data) // 当前项目的所有路由对应关系值！
var ROUTER_TEMPLATE = `/ 此文件来自根目录create-file-router创建： '运行npm run create-router'，
注意：这个文件不是手动写入的信息，不需要改动这个文件，是用来项目里面查看路由表，方便页面的跳转 */
//! 注意，注意， 注意，因为我们是自定义服务器路由，我们需要一个路由表。建议你，先查看根目录config文件是否包含了
//! yp-router.js文件，因为这个文件非常的关键！如果没有这个文件，你应该执行：npm run create-router去生成路由表。
//! 如果你改动了page下面的文件路径，文件名, 文件添加 删除，您应该都需要去执行：npm run create-router
//! 您可能会问，为啥我不执行npm run start的时候，先去执行npm run create-router，因为每次启动去执行一个：npm run create-router 没那个必要。路由不是每次都会改动。

//!重要文件，不要删除！！！

// 如果你需要在项目中跳转页面，记住你不能在按照next官方跳转pages路径方式（也就是clientPath字段）不可取的这是
// 你需要router.push('当前路由表中的path字段')

// 注意如果你这个表中的路由不存在，你就跳转router.push，那页面是匹配不到的！
// 假如你现在再pages添加了一个页面 你不能直接去router.push，你需要运行npm run create-router先去生成路由表！再去跳转页面！

var routerData = [
{{list}}
]
module.exports = routerData
var routetTemplate = [] var ROUTER_ITEM_TEMPLATE = '{ clientPath: "{{clientPath}}", path: "{{path}}", title: "{{title}}" }' data.forEach(item => { routetTemplate.push(render(ROUTER_ITEM_TEMPLATE, { clientPath: item.clientPath, path: item.path, title: item.title })) }) var template = render(ROUTER_TEMPLATE, { list: routetTemplate.join(',' + endOfLine) }) // 写入文件 fs.writeFileSync(OUTPUT_PATH, template) })

[VinayaSathyanarayana]

Ability to generate OpenAPI Specs will be great

[ShubhamKushwah]

There isn't a built-in way to do this, however you can use open-source tools like Slate or ReDoc for generating the UI for you, although manual data entry is still required, and there's nothing wrong with it.

[rafinskipg]

do you have an example of how to use this with nextjs?

[TedisAgolli]

I made a little npm library that auto-generates Swagger docs from your NextJS project. No user input needed!
Still very Beta but hope it helps someone
https://www.npmjs.com/package/nextjs-routes-docs

Just run
npx nextjs-routes-docs [dir]

[maiconsanson]

It would be great to have a GitHub public repo and if it was compatible with the app folder.
Because the API folder is always suffixed with pages/api.

[anthgrim]

I don't know if my response is still relevant at this point but, I found this library that has helped me out building the api docs using swagger
https://www.npmjs.com/package/next-swagger-doc

You would need to install next-swagger-doc and swagger-ui-react to make it work

[Jay-study-nildana]

@anthgrim

aha! very nice. I found this very useful. thank you for sharing brotha.

Jay.

[Cajuteq]

Hi, we are using https://github.com/blomqma/next-rest-framework for the purpose of having a Swagger for our API. The project is very early, but it would be very cool if this or a similar tool could gain traction and perhaps be integrated in NEXT

I have the feeling that with the introduction of server side component in Next 13, more and more people will have a need to access their API documentation

[Jay-study-nildana]

I like it. thank you for sharing it here.

[realsircodesalot]

This looks really polished! Nice find! 😎

[billy-the-ape]

Cannot get any of the solutions suggested here to work at all. How is this not a more highly demanded feature??

[euaaron]

Has anyone got it working with Next13 under /app/api?
Here it works with errors during development and breaks during build...

Error occurred prerendering page "/api". Read more: https://nextjs.org/docs/messages/prerender-error
TypeError: Class extends value undefined is not a constructor or null

I'm using just swagger-ui-react like that:

And writing all route docs to a single .json file that I've put at /public dir.

[themegabyte]

Still looking for a solution that helps automate API doc generation.

[hawkeye-sama]

+1

[SpiralOutDotEu]

I needed something like that, so I built one:

• Scans my nextjs, app router, ts, app folder
• Generates a swagger json
• serves it so that you can check it in http://localhost:3333/docs/

Try it with:

npx nextjs-swagger-gen -a /path/to/your/app -o /path/to/write/swagger.json

or simply from the root of your next project with :

npx nextjs-swagger-gen -a ./app -o ./swagger.json

It is custom for my needs for a nextjs, app router, ts, project, but the code is also there if you want to adapt it on your case.
https://github.com/SpiralOutDotEu/nextjs-swagger-gen