mirror of
https://github.com/immich-app/immich.git
synced 2024-12-25 10:43:13 +02:00
Add generated openapi docs to website (#1067)
* Add generated openapi docs to website * Uppercase API link in navbar * fix(docs): open api empty summary (#1069) * feat(docs): Use /docs/api path for swagger docs * Sync api version to be the same as the server * Update version Co-authored-by: Jason Rasmussen <jrasm91@gmail.com> Co-authored-by: Alex Tran <alex.tran1502@gmail.com>
This commit is contained in:
parent
1adf8ff6b6
commit
a97b761eda
@ -30,8 +30,8 @@ const config = {
|
||||
|
||||
presets: [
|
||||
[
|
||||
"classic",
|
||||
/** @type {import('@docusaurus/preset-classic').Options} */
|
||||
"docusaurus-preset-openapi",
|
||||
/** @type {import('docusaurus-preset-openapi').Options} */
|
||||
({
|
||||
docs: {
|
||||
showLastUpdateAuthor: true,
|
||||
@ -42,6 +42,10 @@ const config = {
|
||||
// Remove this to remove the "edit this page" links.
|
||||
editUrl: "https://github.com/immich-app/immich/tree/main/docs/",
|
||||
},
|
||||
api: {
|
||||
path: "../server/immich-openapi-specs.json",
|
||||
routeBasePath: "/docs/api"
|
||||
},
|
||||
// blog: {
|
||||
// showReadingTime: true,
|
||||
// editUrl: "https://github.com/immich-app/immich/tree/main/docs/",
|
||||
@ -80,6 +84,11 @@ const config = {
|
||||
position: "right",
|
||||
label: "Documentation",
|
||||
},
|
||||
{
|
||||
to: "/docs/api",
|
||||
position: "right",
|
||||
label: "API"
|
||||
},
|
||||
{ to: "/blog", label: "Blog", position: "right" },
|
||||
{
|
||||
href: "https://github.com/immich-app/immich",
|
||||
|
2742
docs/package-lock.json
generated
2742
docs/package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -19,9 +19,11 @@
|
||||
"@docusaurus/preset-classic": "2.1.0",
|
||||
"@mdx-js/react": "^1.6.22",
|
||||
"clsx": "^1.2.1",
|
||||
"docusaurus-preset-openapi": "^0.6.3",
|
||||
"prism-react-renderer": "^1.3.5",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2"
|
||||
"react-dom": "^17.0.2",
|
||||
"url": "^0.11.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@docusaurus/module-type-aliases": "2.1.0",
|
||||
|
BIN
mobile/openapi/lib/api/asset_api.dart
generated
BIN
mobile/openapi/lib/api/asset_api.dart
generated
Binary file not shown.
BIN
mobile/openapi/test/asset_api_test.dart
generated
BIN
mobile/openapi/test/asset_api_test.dart
generated
Binary file not shown.
@ -9,6 +9,7 @@ import { AppModule } from './app.module';
|
||||
import { serverVersion } from './constants/server_version.constant';
|
||||
import { RedisIoAdapter } from './middlewares/redis-io.adapter.middleware';
|
||||
import { json } from 'body-parser';
|
||||
import { patchOpenAPI } from './utils/patch-open-api.util';
|
||||
|
||||
async function bootstrap() {
|
||||
const app = await NestFactory.create<NestExpressApplication>(AppModule);
|
||||
@ -26,7 +27,7 @@ async function bootstrap() {
|
||||
const config = new DocumentBuilder()
|
||||
.setTitle('Immich')
|
||||
.setDescription('Immich API')
|
||||
.setVersion('1.17.0')
|
||||
.setVersion(`${serverVersion.major}.${serverVersion.minor}.${serverVersion.patch}`)
|
||||
.addBearerAuth({
|
||||
type: 'http',
|
||||
scheme: 'Bearer',
|
||||
@ -55,7 +56,7 @@ async function bootstrap() {
|
||||
if (process.env.NODE_ENV == 'development') {
|
||||
// Generate API Documentation only in development mode
|
||||
const outputPath = path.resolve(process.cwd(), 'immich-openapi-specs.json');
|
||||
writeFileSync(outputPath, JSON.stringify(apiDocument, null, 2), { encoding: 'utf8' });
|
||||
writeFileSync(outputPath, JSON.stringify(patchOpenAPI(apiDocument), null, 2), { encoding: 'utf8' });
|
||||
Logger.log(
|
||||
`Running Immich Server in DEVELOPMENT environment - version ${serverVersion.major}.${serverVersion.minor}.${serverVersion.patch}`,
|
||||
'ImmichServer',
|
||||
|
28
server/apps/immich/src/utils/patch-open-api.util.ts
Normal file
28
server/apps/immich/src/utils/patch-open-api.util.ts
Normal file
@ -0,0 +1,28 @@
|
||||
import { OpenAPIObject } from '@nestjs/swagger';
|
||||
|
||||
export function patchOpenAPI(document: OpenAPIObject) {
|
||||
for (const path of Object.values(document.paths)) {
|
||||
const operations = {
|
||||
get: path.get,
|
||||
put: path.put,
|
||||
post: path.post,
|
||||
delete: path.delete,
|
||||
options: path.options,
|
||||
head: path.head,
|
||||
patch: path.patch,
|
||||
trace: path.trace,
|
||||
};
|
||||
|
||||
for (const operation of Object.values(operations)) {
|
||||
if (!operation) {
|
||||
continue;
|
||||
}
|
||||
|
||||
if (operation.summary === '') {
|
||||
delete operation.summary;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return document;
|
||||
}
|
@ -733,7 +733,6 @@
|
||||
"/asset": {
|
||||
"get": {
|
||||
"operationId": "getAllAssets",
|
||||
"summary": "",
|
||||
"description": "Get all AssetEntity belong to the user",
|
||||
"parameters": [
|
||||
{
|
||||
@ -850,7 +849,6 @@
|
||||
"/asset/{deviceId}": {
|
||||
"get": {
|
||||
"operationId": "getUserAssetsByDeviceId",
|
||||
"summary": "",
|
||||
"description": "Get all asset of a device that are in the database, ID only.",
|
||||
"parameters": [
|
||||
{
|
||||
@ -890,7 +888,6 @@
|
||||
"/asset/assetById/{assetId}": {
|
||||
"get": {
|
||||
"operationId": "getAssetById",
|
||||
"summary": "",
|
||||
"description": "Get a single asset's information",
|
||||
"parameters": [
|
||||
{
|
||||
@ -927,7 +924,6 @@
|
||||
"/asset/{assetId}": {
|
||||
"put": {
|
||||
"operationId": "updateAsset",
|
||||
"summary": "",
|
||||
"description": "Update an asset",
|
||||
"parameters": [
|
||||
{
|
||||
@ -974,7 +970,6 @@
|
||||
"/asset/check": {
|
||||
"post": {
|
||||
"operationId": "checkDuplicateAsset",
|
||||
"summary": "",
|
||||
"description": "Check duplicated asset before uploading - for Web upload used",
|
||||
"parameters": [],
|
||||
"requestBody": {
|
||||
@ -1012,7 +1007,6 @@
|
||||
"/asset/exist": {
|
||||
"post": {
|
||||
"operationId": "checkExistingAssets",
|
||||
"summary": "",
|
||||
"description": "Checks if multiple assets exist on the server and returns all existing - used by background backup",
|
||||
"parameters": [],
|
||||
"requestBody": {
|
||||
@ -2108,7 +2102,7 @@
|
||||
"info": {
|
||||
"title": "Immich",
|
||||
"description": "Immich API",
|
||||
"version": "1.17.0",
|
||||
"version": "1.37.0",
|
||||
"contact": {}
|
||||
},
|
||||
"tags": [],
|
||||
|
24
web/src/api/open-api/api.ts
generated
24
web/src/api/open-api/api.ts
generated
@ -2685,7 +2685,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
|
||||
return {
|
||||
/**
|
||||
* Check duplicated asset before uploading - for Web upload used
|
||||
* @summary
|
||||
* @param {CheckDuplicateAssetDto} checkDuplicateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -2725,7 +2724,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
|
||||
},
|
||||
/**
|
||||
* Checks if multiple assets exist on the server and returns all existing - used by background backup
|
||||
* @summary
|
||||
* @param {CheckExistingAssetsDto} checkExistingAssetsDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -2889,7 +2887,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
|
||||
},
|
||||
/**
|
||||
* Get all AssetEntity belong to the user
|
||||
* @summary
|
||||
* @param {string} [ifNoneMatch] ETag of data already cached on the client
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -2928,7 +2925,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
|
||||
},
|
||||
/**
|
||||
* Get a single asset\'s information
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3218,7 +3214,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
|
||||
},
|
||||
/**
|
||||
* Get all asset of a device that are in the database, ID only.
|
||||
* @summary
|
||||
* @param {string} deviceId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3342,7 +3337,6 @@ export const AssetApiAxiosParamCreator = function (configuration?: Configuration
|
||||
},
|
||||
/**
|
||||
* Update an asset
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {UpdateAssetDto} updateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
@ -3440,7 +3434,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
|
||||
return {
|
||||
/**
|
||||
* Check duplicated asset before uploading - for Web upload used
|
||||
* @summary
|
||||
* @param {CheckDuplicateAssetDto} checkDuplicateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3451,7 +3444,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
|
||||
},
|
||||
/**
|
||||
* Checks if multiple assets exist on the server and returns all existing - used by background backup
|
||||
* @summary
|
||||
* @param {CheckExistingAssetsDto} checkExistingAssetsDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3494,7 +3486,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
|
||||
},
|
||||
/**
|
||||
* Get all AssetEntity belong to the user
|
||||
* @summary
|
||||
* @param {string} [ifNoneMatch] ETag of data already cached on the client
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3505,7 +3496,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
|
||||
},
|
||||
/**
|
||||
* Get a single asset\'s information
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3583,7 +3573,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
|
||||
},
|
||||
/**
|
||||
* Get all asset of a device that are in the database, ID only.
|
||||
* @summary
|
||||
* @param {string} deviceId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3616,7 +3605,6 @@ export const AssetApiFp = function(configuration?: Configuration) {
|
||||
},
|
||||
/**
|
||||
* Update an asset
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {UpdateAssetDto} updateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
@ -3648,7 +3636,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
|
||||
return {
|
||||
/**
|
||||
* Check duplicated asset before uploading - for Web upload used
|
||||
* @summary
|
||||
* @param {CheckDuplicateAssetDto} checkDuplicateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3658,7 +3645,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
|
||||
},
|
||||
/**
|
||||
* Checks if multiple assets exist on the server and returns all existing - used by background backup
|
||||
* @summary
|
||||
* @param {CheckExistingAssetsDto} checkExistingAssetsDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3697,7 +3683,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
|
||||
},
|
||||
/**
|
||||
* Get all AssetEntity belong to the user
|
||||
* @summary
|
||||
* @param {string} [ifNoneMatch] ETag of data already cached on the client
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3707,7 +3692,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
|
||||
},
|
||||
/**
|
||||
* Get a single asset\'s information
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3777,7 +3761,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
|
||||
},
|
||||
/**
|
||||
* Get all asset of a device that are in the database, ID only.
|
||||
* @summary
|
||||
* @param {string} deviceId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3807,7 +3790,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
|
||||
},
|
||||
/**
|
||||
* Update an asset
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {UpdateAssetDto} updateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
@ -3837,7 +3819,6 @@ export const AssetApiFactory = function (configuration?: Configuration, basePath
|
||||
export class AssetApi extends BaseAPI {
|
||||
/**
|
||||
* Check duplicated asset before uploading - for Web upload used
|
||||
* @summary
|
||||
* @param {CheckDuplicateAssetDto} checkDuplicateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3849,7 +3830,6 @@ export class AssetApi extends BaseAPI {
|
||||
|
||||
/**
|
||||
* Checks if multiple assets exist on the server and returns all existing - used by background backup
|
||||
* @summary
|
||||
* @param {CheckExistingAssetsDto} checkExistingAssetsDto
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3896,7 +3876,6 @@ export class AssetApi extends BaseAPI {
|
||||
|
||||
/**
|
||||
* Get all AssetEntity belong to the user
|
||||
* @summary
|
||||
* @param {string} [ifNoneMatch] ETag of data already cached on the client
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3908,7 +3887,6 @@ export class AssetApi extends BaseAPI {
|
||||
|
||||
/**
|
||||
* Get a single asset\'s information
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -3994,7 +3972,6 @@ export class AssetApi extends BaseAPI {
|
||||
|
||||
/**
|
||||
* Get all asset of a device that are in the database, ID only.
|
||||
* @summary
|
||||
* @param {string} deviceId
|
||||
* @param {*} [options] Override http request option.
|
||||
* @throws {RequiredError}
|
||||
@ -4030,7 +4007,6 @@ export class AssetApi extends BaseAPI {
|
||||
|
||||
/**
|
||||
* Update an asset
|
||||
* @summary
|
||||
* @param {string} assetId
|
||||
* @param {UpdateAssetDto} updateAssetDto
|
||||
* @param {*} [options] Override http request option.
|
||||
|
Loading…
Reference in New Issue
Block a user