beenull/immich
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add generated openapi docs to website (#1067)

Browse source 
* 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:
bo0tzz 2022-12-08 04:57:34 +01:00 committed by GitHub
parent 1adf8ff6b6
commit a97b761eda
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 2787 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
docs/docusaurus.config.js
View file

@ -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
View file

File diff suppressed because it is too large Load diff

4
docs/package.json
View file

@ -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",

24
mobile/openapi/lib/api/asset_api.dart generated
View file

@ -16,8 +16,6 @@ class AssetApi {
final ApiClient apiClient;
///
///
/// Check duplicated asset before uploading - for Web upload used
///
/// Note: This method returns the HTTP [Response].
@ -50,8 +48,6 @@ class AssetApi {
);
}
///
///
/// Check duplicated asset before uploading - for Web upload used
///
/// Parameters:
@ -72,8 +68,6 @@ class AssetApi {
return null;
}
///
///
/// Checks if multiple assets exist on the server and returns all existing - used by background backup
///
/// Note: This method returns the HTTP [Response].
@ -106,8 +100,6 @@ class AssetApi {
);
}
///
///
/// Checks if multiple assets exist on the server and returns all existing - used by background backup
///
/// Parameters:
@ -292,8 +284,6 @@ class AssetApi {
return null;
}
///
///
/// Get all AssetEntity belong to the user
///
/// Note: This method returns the HTTP [Response].
@ -331,8 +321,6 @@ class AssetApi {
);
}
///
///
/// Get all AssetEntity belong to the user
///
/// Parameters:
@ -357,8 +345,6 @@ class AssetApi {
return null;
}
///
///
/// Get a single asset's information
///
/// Note: This method returns the HTTP [Response].
@ -392,8 +378,6 @@ class AssetApi {
);
}
///
///
/// Get a single asset's information
///
/// Parameters:
@ -740,8 +724,6 @@ class AssetApi {
return null;
}
///
///
/// Get all asset of a device that are in the database, ID only.
///
/// Note: This method returns the HTTP [Response].
@ -775,8 +757,6 @@ class AssetApi {
);
}
///
///
/// Get all asset of a device that are in the database, ID only.
///
/// Parameters:
@ -913,8 +893,6 @@ class AssetApi {
return null;
}
///
///
/// Update an asset
///
/// Note: This method returns the HTTP [Response].
@ -950,8 +928,6 @@ class AssetApi {
);
}
///
///
/// Update an asset
///
/// Parameters:

12
mobile/openapi/test/asset_api_test.dart generated
View file

@ -17,8 +17,6 @@ void main() {
// final instance = AssetApi();
group('tests for AssetApi', () {
//
//
// Check duplicated asset before uploading - for Web upload used
//
//Future<CheckDuplicateAssetResponseDto> checkDuplicateAsset(CheckDuplicateAssetDto checkDuplicateAssetDto) async
@ -26,8 +24,6 @@ void main() {
// TODO
});
//
//
// Checks if multiple assets exist on the server and returns all existing - used by background backup
//
//Future<CheckExistingAssetsResponseDto> checkExistingAssets(CheckExistingAssetsDto checkExistingAssetsDto) async
@ -50,8 +46,6 @@ void main() {
// TODO
});
//
//
// Get all AssetEntity belong to the user
//
//Future<List<AssetResponseDto>> getAllAssets({ String ifNoneMatch }) async
@ -59,8 +53,6 @@ void main() {
// TODO
});
//
//
// Get a single asset's information
//
//Future<AssetResponseDto> getAssetById(String assetId) async
@ -103,8 +95,6 @@ void main() {
// TODO
});
//
//
// Get all asset of a device that are in the database, ID only.
//
//Future<List<String>> getUserAssetsByDeviceId(String deviceId) async
@ -122,8 +112,6 @@ void main() {
// TODO
});
//
//
// Update an asset
//
//Future<AssetResponseDto> updateAsset(String assetId, UpdateAssetDto updateAssetDto) async

5
server/apps/immich/src/main.ts
View file

@ -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
View 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;
}

8
server/immich-openapi-specs.json
View file

@ -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
View file

@ -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.