azure / api-portal Goto Github PK

API Portal lets you create and publish a customized site with API documentation, for free and without writing any code.

License: MIT License

JavaScript 1.51% TypeScript 58.17% HTML 13.40% Liquid 3.18% SCSS 23.75%

api api-catalog api-documentation static-site-generator

api-portal's Introduction

API Portal

API Portal lets you create and publish a customized site with API documentation, for free and without writing any code. GitHub-based workflow enables collaboration between API providers and API consumers, source control, automation, and free hosting.

See the demo of a published API portal.

Highlights

Modern API documentation portal. Create a modern API documentation portal with REST API reference pages, code samples, and interactive console. Customize it through a drag-and-drop, no-code visual editor.
GitHub-based API ecosystem. Create a GitHub-based API ecosystem for communication and collaboration between API providers and API consumers. Track source code changes, automate portal deployments with GitHub Actions, and host the site for free with GitHub Pages.
Enterprise-wide API catalog. Publish the portal within the organization to catalog APIs for discoverability, deduplication of assets, and business efficiency.
Branded API documentation portal. Publish the branded portal to partners or external consumers for discoverability and self-onboarding.
Proven technology. API Portal relies on the same technology as the Azure API Management’s developer portal (documentation, GitHub), which is used by thousands of Microsoft Azure customers.

Get started

The tutorial in the wiki section describes how to publish the first API, customize the portal, and publish it with GitHub Pages or your preferred hosting solution.

api-portal's People

Contributors

Stargazers

Watchers

Forkers

azaslonov gfchaves cplemm stap123 mikebudzynski 11yusuf raunaknarooka buildingbridge dotam99 akishaha crocom christiannagel javipriego bookingstudio agiledave ypiyush2595 piyushyadav-ib zeta1999 sourabhshrivastava2141 superjamel jonasinghammar rajdn aizefler doutoraovivo ns-abe-jun berberich dawmatt skalapa seanksullivan 195858 thecloudelastic joonasjonas mw-digital-creators skolbin-ssi winmike mignet76 callingpeter tighedev alfechner godslayer972 escgc kkchanuofi bernatorg thomasgoldstein victor-rodriguez-codeoscopic vernalbehemoth ratkas vvilelaj homesmart0 samlex20 mysticparrot bradleyhart bizdemo noqodidevportal masoudsoleymani uw-creator myafka wcatlyn-bluebean onaldanm fred071 orgscsgitdev mondora kevin-phan90 vik-bht vikbht igarro nikhil1978 poc-inc diogopainho jijujacob jharbieh-microsoft gaurav46 sspim-api-portal gprvn uniqkod metjuperry rga-atl luisfernandocneves milanc avpatel257 selaue horatiohe jeffchong jejoswaks eallison123 anuraagkamath007 cigaciga isabella232 wi-five geeraertherber pratikdholakia rupertberk pferreyra84 martinstenhoff guoqqqi ohmyr9 jihyeon121223 wdoonfack jcrowdertealbook daneel3001

api-portal's Issues

Errors deploying gh-pages branch

Steps to get to this point:

Fork the repo
Choose to deploy from gh-pages branch via Actions
Change publish-on-checkin.yml to point to node 16 and v3 actions
Add a dummy file called /templates/default.json to get past the build failing on that file missing
Pulled down code, build and ran designer, made a basic change and saved it (change was to add text)
Push changes back up to the repo and then the pipeline attempts to build and deploy

Getting the following error (happens even before steps 5 and 6 above):

Push the commit or tag
/usr/bin/git push origin gh-pages
remote: Permission to QED-DeveloperPortal/API-Portal.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/QED-DeveloperPortal/API-Portal.git/': The requested URL returned error: 403
Error: Action failed with "The process '/usr/bin/git' failed with exit code 128"

Clarify development path compared to self-hosted version

We now have 2 versions of the portal code base with some slight differences:

This brings some questions:

Will this API-Portal replace the other one eventually? This is important to know, because if you've setup the self-hosted one with the https://github.com/Azure/api-management-developer-portal and some devops pipelines, there doesn't seem to be much reason to move away.
Will the 2 versions have separate development and features eventually? Apart from the way you can release it, there doesn't seem to be much difference yet.

Update GitHub Actions to use Node 16

Currently getting this error when trying to deploy to GitHub Pages:

Node.js 12 actions are deprecated. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/. Please update the following actions to use Node.js 16: actions/checkout, actions/setup-node, actions/checkout

I have forked and tried to change the contents of .workflow to point to Node 16 but to no avail.

Local install not working, nor advanced deployments

Installs/deployments no longer seem to be working. They typically complain about apim-developer-portal being missing:

npm ERR! Failed at the [email protected] publish script.

These errors stop any deployments from working, and the deployments are being performed in alignment with the wiki.

The wiki contains "Customize the site" steps ( https://github.com/Azure/API-Portal/wiki ) as follows:

Clone the forked repository to your local environment.
Launch the server.
1. Open the command line and navigate to the catalog folder with the command cd catalog.
2. Run npm install to resolve dependencies.
3. Run npm start to start a local server.

At step 2.b the following warning is returned:

npm WARN [email protected] No repository field.

At step 2.b the following error is returned, and the website refuses to accepted connections:

WARNING in ./node_modules/any-promise/register.js 24:14-37
Critical dependency: the request of a dependency is an expression
 @ ./node_modules/any-promise/index.js 1:17-38
 @ ./node_modules/koa-router/node_modules/koa-compose/index.js 3:16-38
 @ ./node_modules/koa-router/lib/router.js 9:14-36
 @ ./node_modules/routing-controllers/esm2015/driver/koa/KoaDriver.js 348:39-60
 @ ./node_modules/routing-controllers/esm2015/index.js 2:0-51 83:0-39 83:0-39 114:23-32 121:23-32
 @ ./src/startup.host.ts 7:30-60

WARNING in ./node_modules/express/lib/view.js 81:13-25
Critical dependency: the request of a dependency is an expression
 @ ./node_modules/express/lib/application.js 22:11-28
 @ ./node_modules/express/lib/express.js 18:12-36
 @ ./node_modules/express/index.js 11:0-41
 @ ./src/startup.host.ts 4:16-34

WARNING in ./node_modules/routing-controllers/esm2015/util/importClassesFromDirectories.js 28:15-28
Critical dependency: the request of a dependency is an expression
 @ ./node_modules/routing-controllers/esm2015/index.js 5:0-83 140:34-62 146:34-62 152:35-63
 @ ./src/startup.host.ts 7:30-60

3 warnings have detailed information that is not shown.
Use 'stats.errorDetails: true' resp. '--stats-error-details' to show it.

ERROR in ./node_modules/routing-controllers/esm2015/ActionParameterHandler.js 2:0-63
Module not found: Error: Can't resolve 'class-validator' in '/Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/routing-controllers/esm2015'
resolve 'class-validator' in '/Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/routing-controllers/esm2015'
  Parsed request is a module
  using description file: /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/routing-controllers/package.json (relative path: ./esm2015)
    resolve as module
      /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/routing-controllers/esm2015/node_modules doesn't exist or is not a directory
      /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/routing-controllers/node_modules doesn't exist or is not a directory
      /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/node_modules doesn't exist or is not a directory
      looking for modules in /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules
        single file module
          using description file: /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/package.json (relative path: ./node_modules/class-validator)
            no extension
              /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/class-validator doesn't exist
            .ts
              /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/class-validator.ts doesn't exist
            .tsx
              /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/class-validator.tsx doesn't exist
            .js
              /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/class-validator.js doesn't exist
            .jsx
              /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/class-validator.jsx doesn't exist
        /Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/class-validator doesn't exist
      /Users/mattdawson/Dev/_Github/OAS-API-Examples/node_modules doesn't exist or is not a directory
      /Users/mattdawson/Dev/_Github/node_modules doesn't exist or is not a directory
      /Users/mattdawson/Dev/node_modules doesn't exist or is not a directory
      looking for modules in /Users/mattdawson/node_modules
        single file module
          No description file found in /Users/mattdawson/node_modules or above
          no extension
            /Users/mattdawson/node_modules/class-validator doesn't exist
          .ts
            /Users/mattdawson/node_modules/class-validator.ts doesn't exist
          .tsx
            /Users/mattdawson/node_modules/class-validator.tsx doesn't exist
          .js
            /Users/mattdawson/node_modules/class-validator.js doesn't exist
          .jsx
            /Users/mattdawson/node_modules/class-validator.jsx doesn't exist
        /Users/mattdawson/node_modules/class-validator doesn't exist
      /Users/node_modules doesn't exist or is not a directory
      /node_modules doesn't exist or is not a directory
 @ ./node_modules/routing-controllers/esm2015/RoutingControllers.js 1:0-66 20:36-58
 @ ./node_modules/routing-controllers/esm2015/index.js 4:0-58 192:8-26
 @ ./src/startup.host.ts 7:30-60


webpack 5.70.0 compiled with 1 error and 3 warnings in 13803 ms
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] start: `webpack --config webpack.designer.js && webpack --config webpack.host.js && node ./dist/host/index.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] start script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:

Similarly the "Advanced deployment options" section on the same page contains the following instructions:

You can also run the publishing step locally and deploy the generated static assets from the /catalog/dist/website folder to the hosting solution of choice instead of GitHub Pages. To run the publishing step, execute the command npm run publish on your local machine.

The npm run publish command returned the following:

WARNING in ./node_modules/ws/lib/buffer-util.js 103:21-42
Module not found: Error: Can't resolve 'bufferutil' in '/Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/ws/lib'
 @ ./node_modules/ws/lib/receiver.js 12:42-66
 @ ./node_modules/ws/index.js 7:21-46
 @ ./node_modules/jsdom/lib/jsdom/living/websockets/WebSocket-impl.js 7:18-31
 @ ./node_modules/jsdom/lib/jsdom/browser/Window.js 21:22-83
 @ ./node_modules/jsdom/lib/api.js 13:25-61
 @ ./node_modules/@paperbits/common/publishing/dominoHtmlDocumentProvider.ts 4:16-32
 @ ./node_modules/@paperbits/common/publishing/index.ts 27:13-52
 @ ./node_modules/@paperbits/core/core.publish.module.ts 11:21-60
 @ ./src/startup.publish.ts 7:30-76

WARNING in ./node_modules/ws/lib/validation.js 109:22-47
Module not found: Error: Can't resolve 'utf-8-validate' in '/Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/node_modules/ws/lib'
 @ ./node_modules/ws/lib/receiver.js 13:43-66
 @ ./node_modules/ws/index.js 7:21-46
 @ ./node_modules/jsdom/lib/jsdom/living/websockets/WebSocket-impl.js 7:18-31
 @ ./node_modules/jsdom/lib/jsdom/browser/Window.js 21:22-83
 @ ./node_modules/jsdom/lib/api.js 13:25-61
 @ ./node_modules/@paperbits/common/publishing/dominoHtmlDocumentProvider.ts 4:16-32
 @ ./node_modules/@paperbits/common/publishing/index.ts 27:13-52
 @ ./node_modules/@paperbits/core/core.publish.module.ts 11:21-60
 @ ./src/startup.publish.ts 7:30-76

2 warnings have detailed information that is not shown.
Use 'stats.errorDetails: true' resp. '--stats-error-details' to show it.

ERROR in unable to locate '/Users/mattdawson/Dev/_Github/OAS-API-Examples/catalog/templates/default.json' glob

webpack 5.70.0 compiled with 1 error and 2 warnings in 43251 ms

assets by path assets/monaco-editor/vs/basic-languages/ 423 KiB 75 assets
assets by path assets/monaco-editor/vs/editor/ 3.94 MiB 12 assets
assets by path assets/monaco-editor/vs/language/ 7.1 MiB 8 assets
assets by path styles/ 110 KiB
  asset styles/theme.css 72.1 KiB [compared for emit] (name: styles/theme)
  + 4 assets
assets by path ./ 6.06 MiB
  asset ./scripts/theme.js 6.06 MiB [compared for emit] (name: scripts/theme)
  asset ./styles/theme.js 2.22 KiB [compared for emit] (name: styles/theme)
assets by path assets/monaco-editor/vs/base/ 243 KiB
  asset assets/monaco-editor/vs/base/worker/workerMain.js 177 KiB [compared for emit] [from: node_modules/monaco-editor/min/vs/base/worker/workerMain.js] [copied]
  asset assets/monaco-editor/vs/base/browser/ui/codicons/codicon/codicon.ttf 66.3 KiB [compared for emit] [from: node_modules/monaco-editor/min/vs/base/browser/ui/codicons/codicon/codicon.ttf] [copied]
asset assets/monaco-editor/vs/loader.js 31.8 KiB [compared for emit] [from: node_modules/monaco-editor/min/vs/loader.js] [copied]
asset page.html 411 bytes [compared for emit] [from: src/themes/website/assets/page.html] [copied]
Entrypoint scripts/theme 6.06 MiB = ./scripts/theme.js
Entrypoint styles/theme 74.3 KiB = styles/theme.css 72.1 KiB ./styles/theme.js 2.22 KiB
orphan modules 76.1 KiB (javascript) 937 bytes (runtime) [orphan] 31 modules
runtime modules 1.52 KiB 7 modules
modules by path ./node_modules/ 4.55 MiB
  javascript modules 4.52 MiB 1132 modules
  json modules 33.5 KiB
    modules by path ./node_modules/entities/ 30 KiB 4 modules
    ./node_modules/cheerio/package.json 1.55 KiB [built] [code generated]
    ./node_modules/truncate-html/node_modules/cheerio/package.json 1.78 KiB [built] [code generated]
    ./node_modules/css-select/lib/procedure.json 126 bytes [built] [code generated]
modules by path ./src/ 337 KiB (javascript) 71.5 KiB (css/mini-extract) 103 modules
readable-stream (ignored) 15 bytes [built] [code generated]
readable-stream (ignored) 15 bytes [built] [code generated]
util (ignored) 15 bytes [built] [code generated]
util (ignored) 15 bytes [built] [code generated]
webpack 5.70.0 compiled successfully in 43243 ms
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] publish: `webpack --config webpack.publisher.js && node dist/publisher/index.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] publish script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:

Can you please help?

How to add api specs by product

Hi There ,

we would like to categorize our apis by product . For this we are planning to define cards on home and provide a link to a product page for list of apis .

There is a api-specs folder , which is kind of generic for all pages . Is there a way to filter the list for defined page ( i.e product) .

Other issue we observed it , pages we added using admin module , can not be used as hyperlink to cards . It always says oops some thing went wrong .

Appreciate your help with this .

Cheers

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request

Provide CODEOWNERS

Provide CODEOWNERS configuration so that PRs can get automatically assigned, such as #53

"npm start" results in error "TS2339: Property 'getType' does not exist on type 'typeof import...."

Hello,

I just wanted to test the current main-line but when executing

cd catalog
npm install
npm start

the process dies with the following error:

ERROR in "/Users/XXXX/api-portal/catalog/node_modules/@paperbits/core/publishing/assetPublisher.ts
    [tsl] ERROR in "/Users/XXXX/api-portal/catalog/node_modules/@paperbits/core/publishing/assetPublisher.ts(17,38)
          TS2339: Property 'getType' does not exist on type 'typeof import("/Users/XXXX/api-portal/catalog/node_modules/@types/mime/index")'.

My system is MacOS

> node --version 
v16.4.0
> npn --version
7.19.1
> sw_vers
ProductName:    macOS
ProductVersion: 11.4
BuildVersion:   20F71

Seeking clarity on API-Portal vs https://github.com/Azure/api-management-developer-portal

We are currently evaluating using this repo as a "mocked responses only" front end for our API portal by integrating it into a larger capability that includes documentation served from GitHub via (GitHub Pages).

We have also looked at integrating https://github.com/Azure/api-management-developer-portal however that seems to require:

AADB2C for external users if we try to host inside GitHub Pages
AAD for internal corporate users
Monthly payments for having it hosted on Azure or at least via Azure Storage if we set up some other internal self-hosting (VNet etc).

Requiring authentication to be able to view mocked APIs feels onerous.

Also, thus far I haven't been able to get an actual "Try It Out" page to show for this current repo. I can only get the designer up and see that changes are saved to a json file.

Going through the source code for the two repos there seems to be some divergence now and not sure what the direction is going forward.

Could someone please advise if there will soon be more work put into this API-Portal repo and what might come out of it?

Add support for YAML format of OpenAPI specification

When I add a YAML file to the api-specs folder and then run npm run publish it results in an error.

Sample OpenAPI file:

openapi: 3.0.0
info:
  title: Simple test
  version: '1.0'
paths:
  /test:
    get:
      responses:
        '204':
          description: No response

Error:

Error: Unable to complete publishing. Error: Unable to complete OpenAPI specifications publishing. SyntaxError: Unexpected token o in JSON at position 0
at JSON.parse ()
at OpenApiPublisher.eval (webpack://publisher/./src/publishing/openApiPublisher.ts?:29:46)
at Generator.next ()
at fulfilled (webpack://publisher/./src/publishing/openApiPublisher.ts?:5:58)
at OpenApiPublisher.eval (webpack://publisher/./src/publishing/openApiPublisher.ts?:39:23)
at Generator.next ()
at fulfilled (webpack://publisher/./src/publishing/openApiPublisher.ts?:5:58)
at SitePublisher.eval (webpack://publisher/./node_modules/@paperbits/core/publishing/sitePublisher.ts?:40:23)
at Generator.throw ()
at rejected (webpack://publisher/./node_modules/@paperbits/core/publishing/sitePublisher.ts?:6:65)

It seems to be trying to parse the YAML file as JSON.

Cannot run local

When trying to run the API-Portal locally, I am getting the following error:

Consider supporting GraphQL SDL

As the title says - it seems you only support REST/Swagger/OpenAPI for the moment. GraphQL would be a nice extension.

Soap API

Discussed in #62

^{Originally posted by gregz1 August 22, 2022}
hello,

as indicated here : https://docs.microsoft.com/en-us/azure/api-management/import-soap-api, the Azure developer portal allows to import a WSDL file to make available a Soap API description into the portal.
Could you confirm that is possible with this version ?
I added a valid WSDL xml file in the api-specs folder and it does not seems to work.

best regards

Configure code splitting to reduce loading time for output files

Looking at the demo site it takes about 16 seconds to load.

I think theme.js could go on a diet, since a cursory glance shows it's not minified.

Question: will the two kinds of Dev-Portals content-wise be compatible?

Great to see this new project! I am looking forward to the possibilities this might offer.

Here my questions:

I wonder if the two kind of DevPortal frameworks, this new Azure API-Portal and the already existing new Azure DevPortal will be compatible in regard to the web contents that are stored in the data/content.json files. This would be very important to us that we would not need to build up the contents and styles in two portals separately and in parallel. What is the current status quo here? And if this is currently not the case - will there be an automated migration path supported? Thank you very much in advance.
Is it only supported to host the API-Portal websites in the Intranet or is it also possible to deploy the websites as an application package locally?
I wonder if this framework would allow us to provide a local portal solution to our customers to install it locally on their PCs or virtualized environment. The idea would be that we could provide it together with another installation package that the user would get from us and that we are able to update API specification on demand via the Intranet automatically at any time. Is this use case already be supported by this framework? Or do you plan it?

openApi docs added - No operations found

Looking at this repo briefly (forgive me if I missed something)

If I add a new, valid openApi json (ver. 3.0.1) file to the api-specs folder, the API will be listed on the home page, but will not display operations within: "No operations found".

The three 'sample' json files work and display as expected. What am I missing?

Stack trace:
Unable to process binding "if: function(){return operations }"
Message: Unable to process binding "foreach: function(){return { data:operations,as:'item'} }"
Message: Unable to process binding "attr: function(){return { href:$component.getReferenceUrl(item)} }"
Message: Parameter "operationName" not specified

please ignore

Support for publishing to GitHub Pages with URL suffix

Currently the setup wiki page for this repo advises:

The portal will be deployed under the URL https://[username].github.io, without a URL path suffix

Can support for publishing to a URL path suffix be added? Currently the code does not operate correctly if published to GitHub Pages with a URL path suffix (the default config after forking the repo). If the user reconfigures the settings to publish as advised by the wiki page, the user is effectively unable to use their GitHub Pages site for any other repositories, limiting the appeal of this project.