Can I use https://github.com/TypeStrong/typedoc to create REST API docs like https://apidocjs.com/?
Any suggestions on how to reuse TypeScript types to generate REST API docs are welcome (Using Next.js)
1
-
1Typedoc will show any JSDoc tags you add but there's no special handling for API doc tags. TypeDoc is more focused on documenting internal code.Chic– Chic2020-11-30 23:13:59 +00:00Commented Nov 30, 2020 at 23:13
Add a comment
|
2 Answers
If what you actually want is to describe your API in TypeScript and have a Swagger/OpenAPI definition come out of it, try https://github.com/airtasker/spot
IT will not only generate REST API documentation, it will also let you run a mock server with random data that fits the REST API definition (for testing clients) and a data model validator (for testing servers).
Example from the project README:
import { api, endpoint, request, response, body } from "@airtasker/spot";
@api({
name: "My API"
})
class Api {}
@endpoint({
method: "POST",
path: "/users"
})
class CreateUser {
@request
request(@body body: CreateUserRequest) {}
@response({ status: 201 })
response(@body body: CreateUserResponse) {}
}
interface CreateUserRequest {
firstName: string;
lastName: string;
}
interface CreateUserResponse {
firstName: string;
lastName: string;
role: string;
}
1 Comment
Denis Zhbankov
sadly, you cannot use bearer authorization and different authorization per endpoint with it
Have you checked the npm package apidoc?
It generates API documentation based on code comments:
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id User's unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
And there are companion tools / converters for Gulp, Grunt, Eclipse, Sublime Text, Docmaster, Markdown, Swagger... (cf. apidoc GitHub README.md)
Comments
