Overhaul of the OpenAPI specifications #1309
Comments
jacobwod
added a commit
that referenced
this issue
Mar 29, 2023
…sion, part of #1309: - I'm defaulting the specification path to V1 for now.
jacobwod
added a commit
that referenced
this issue
Mar 29, 2023
- In V1 spec:
- Removed definitions to the new HTTP verbs, they aren't supposed to be part of V1 spec
- Removed the depracation warnings on V1 endpoints
- Fixed server definition and API version number
- In V2 spec:
- Removed all endpoints previously marked as depracated, including those with duplicate
HTTP verbs. Only the correct verbs remain in V2.
- Removed GET /mapconfig/create/{map} and GET /mapconfig/delete/{map}. They are both
taken care of using PUT respectively DELETE /mapconfig/{name}.
- Fixed server definition and API version number
- Necessary changes in server.js to accomodate for the new file names.
jacobwod
added a commit
that referenced
this issue
Mar 30, 2023
- v1 and v2 have their own dirs
- I appended a .v2 to all logger definitions for API V2 controllers/services
- I removed the obsolete endpoints from V2
- Added the new endpoints: PUT and DELETE /mapconfig/{name} instead of /mapconfig/create/{name} and /mapconfig/delete/{name}. This was already changed in the API spec so we will now conform to that
- This is by no means complete (at least I think there's room for improvement). See this as a proposal for future structure inside the Backend dir and please let me know what you think in #1309.
|
As I mentioned in my last commit, I had a feeling that this will need some more work. Now I see one place that needs re-thinking.
|
|
I've come a long way in https://github.com/hajkmap/Hajk/commits/feature/1309-api-v1-v2-separation-in-nodejs-backend as of today. All endpoints and middlewares are versioned, except for one: the one that reads our And I think that we want to keep it this way. I.e., in will expose contents of I wouldn't like it to be placed under But you could also see it as this middleware makes use of stuff that are prone to change in future version (e.g. the AD service). So we should version it, huh…? I don't know. Opinions all, ping @jesade-vbg @Hallbergs? |
|
I agree that the exposed static dirs should be available directly on Maybe some functionality could be seen as some kind of "core-api"? These could be set to always use the last stable services (v2 in this case). Another solution could be to see the exposing of static folders as a "one-of" and have a separate setting for that middleware in |
|
Good idea, that's what I ended up with as of 4066ce3. Pretty much done now I think. |
jacobwod
added a commit
that referenced
this issue
Apr 13, 2023
* Total restructuring inside the /api dir:
- v1 and v2 have their own dirs
- I appended a .v2 to all logger definitions for API V2 controllers/services
- I removed the obsolete endpoints from V2
- Added the new endpoints: PUT and DELETE /mapconfig/{name} instead of /mapconfig/create/{name} and /mapconfig/delete/{name}. This was already changed in the API spec so we will now conform to that
- This is by no means complete (at least I think there's room for improvement). See this as a proposal for future structure inside the Backend dir and please let me know what you think in #1309.
* Next step in the transision: clean up the Router a bit
* Another step forward:
- Separation of API requires either duplicating a lot of functionality (common to the API versions) or drawing a line somewhere and saying 'hey, this part of code should be shared between versions'.
- That's what I'm attemptign to do here and opinions are welcome.
- The 'line' is currently drawn at 'stuff that don't expose /api/vN endpoint should be shared'. So we share the error handler, logger and detailed logger middlewares. The proxy middlewares and perhaps even the static files exposer middleware will be placed inside each API's version. That will come in a future commit.
* Prepared two product proxies for versioning.
* Major changes in server.js to make room for versioning:
- Added a key in .env, API_VERSIONS. It can contain a comma-separated list of integers that corespond to API versions. By default any empty value or no value at all means that all API versions are enabled.
- Added a apiVersions constant both in server.js and as an Express app variable, so we can do app.get(apiVersions) anywhere and get the array. Nice.
- Moved two product proxies (FME Server and Sokigo FB) to helper methods. Inside of them, we iterate and import required proxies dynamically.
- Another iteration takes place to set up the OpenAPI Validator middleware and expose the specification, depending on which versions are required. Also nice.
* Disabled http-middleware-proxy's internal logging:
- There were issues with it: seemingly the last middleware to be setup got all logging messages to it, which is unintended.
- The logging we setup ourselves in the middlewares is fine though. Since we take care of both success and error and log
then correctly, there was no use for HPM's internal logging.
* Small cleanups
* Generic proxy versioning added. Also major improvements to API version check.
- The generic proxy is not really versioned as it merely exposes some endpoints using HTTP Proxy Middleware. But we do expose proxies for each of the enabled versions of API to keep it consistent with previous Hajk versions.
- The check added at startup ensure that we only attempt to initialize valid API versions. Those are, for now, kept in const ALLOWED_API_VERSIONS but could be moved further on.
* Version bumped logger
* Discovered that the Router imports all API versions - must be fixed prior release.
* Added coherent initialization messages to Services in V2
* Added version info to V1 middlewares, for consistency.
* The Static Exposer is now versioned too:
- The static routes are still exposed outside the /api/vN, but the code used is dynamically imported.
- Admin can specify a certain version of active API versions to use. Default value is the highest (latest) active API version.
* Routes are created only for the active API versions, takes care of the bug discovered in 59b7915.
jacobwod
added a commit
that referenced
this issue
Apr 28, 2023
…een imported: - This was discovered in #1332 but the problem first came up in #1309. - OAV will only take care of routes that exists when the middleware runs. Hence, any async imports that haven't yet run will be unknown to the OAV and render a 404. - This ugly setTimeout fix takes care of it but I'm open for a better solution (including discussing the future of OAV in our Backend).
jacobwod
added a commit
that referenced
this issue
May 9, 2023
* First step towards making Backend fully ESM-compatible: - Necessary changes made in package.json - Most other changes are due to a missing file extension in most imports. - One small change was that __dirname isn't available when using ESM, so I changed the way we resolve path to the YAML specifications by using process.cwd(), as we do in other fs.* functions. - I'm testing the VSCode-GitHub integration now, hence the branch name that does not follow our convention - sorry * Removed Babel, etc: - Removed Babel, including: 'compile' step in package.json and other commands, all dependencies and configuration file - Replaced the 'compile' step with a basic copy of directory to dist/. The reasoning behind this is that it let's us continue using current Dockerfiles etc without any changes. - Major cleanups in ESlint config. Seems good so far, check out the screenshot in this issue: #1328 - Moved Prettier's config to an own file - Prettier seems fine too, see screenshot above - If this works as intended, we have a much cleaner toolchain. NodeJS 16+ is now required but it shouldn't be a major problem. * Added missing definition, no idea how it got lost. * New lock file after clean deps install. Should close #1328. * Workaround the fact that __dirname isn't available in ESM. This pretty much closes #1328. * Ensure that the OpenApiValidator runs _after_ any async routes have been imported: - This was discovered in #1332 but the problem first came up in #1309. - OAV will only take care of routes that exists when the middleware runs. Hence, any async imports that haven't yet run will be unknown to the OAV and render a 404. - This ugly setTimeout fix takes care of it but I'm open for a better solution (including discussing the future of OAV in our Backend). * Minor fix in Prettier config to reflect that we use LF for new line throughout the project.
sweco-semara
added a commit
to sweco-se/hajk-fork
that referenced
this issue
Sep 8, 2023
* Link to issue hajkmap#1309 (API version separation)
sweco-semara
added a commit
to sweco-se/hajk-fork
that referenced
this issue
Sep 8, 2023
* Link to issue hajkmap#1309 (API version separation)
Hallbergs
pushed a commit
that referenced
this issue
Sep 12, 2023
jacobwod
added a commit
that referenced
this issue
Mar 7, 2024
* npm up * Added the ENABLE_WEBSOCKETS variable to .env so we can easily turn this functionality on and off. * Streamlining Halmstad's production branch, removed unused components. * Changed browserslist to a simple 'defaults' only. * Added an optional hyphen and centered the app load text. * Deps bump for Backend * Since the separation of V1 and V2 APIs, hajkLogger has been moved to utils. * First step towards making Backend fully ESM-compatible: - Necessary changes made in package.json - Most other changes are due to a missing file extension in most imports. - One small change was that __dirname isn't available when using ESM, so I changed the way we resolve path to the YAML specifications by using process.cwd(), as we do in other fs.* functions. - I'm testing the VSCode-GitHub integration now, hence the branch name that does not follow our convention - sorry * Removed Babel, etc: - Removed Babel, including: 'compile' step in package.json and other commands, all dependencies and configuration file - Replaced the 'compile' step with a basic copy of directory to dist/. The reasoning behind this is that it let's us continue using current Dockerfiles etc without any changes. - Major cleanups in ESlint config. Seems good so far, check out the screenshot in this issue: #1328 - Moved Prettier's config to an own file - Prettier seems fine too, see screenshot above - If this works as intended, we have a much cleaner toolchain. NodeJS 16+ is now required but it shouldn't be a major problem. * Added missing definition, no idea how it got lost. * New lock file after clean deps install. Should close #1328. * Workaround the fact that __dirname isn't available in ESM. This pretty much closes #1328. * Removed Windows Service references as they're not needed in our environment. * Fixes to the WebSocket part that exists in this branch, its imports must also be converted to ESM of course. * Ensure that the OpenApiValidator runs _after_ any async routes have been imported: - This was discovered in #1332 but the problem first came up in #1309. - OAV will only take care of routes that exists when the middleware runs. Hence, any async imports that haven't yet run will be unknown to the OAV and render a 404. - This ugly setTimeout fix takes care of it but I'm open for a better solution (including discussing the future of OAV in our Backend). * npm i * Upgraded query-string that awaited the completition of #1328. * I need to bump the version number across the product to easily keep track of running versions. * This has grown pretty big since yesterday, time for an initial commit: - WIP so expect a lot of warnings - See #1360 for issue - See also the README.md in the plugin's dir for more info on configuration. * Now also passing down the coordinates of clicked point. * Revert "Merge pull request #1346 from hajkmap/feature/1316-PermanentDrawerOption" This reverts commit 38564d6, reversing changes made to dbbc37e. This will be re-merged once #1367 is closed. * GeosuiteExport is not part of our toolset. * We've successfully migrated Draw->Sketch so there's no need to include it in the build anymore. * Fix for #1309: import of XMLParser fell behind in the V2 API after the split. Corrected now. * Some significant dependencies bumped to latest versions: - Most notably a couple of our dependencies now dropped support for Node 8 (which we don't support anyway), so shouldn't be breaking to us. * Infoclick: allow for some common Markdown and URL characters inside the infoclick placeholder string: - I've implemented both of the proposals from #1368 in this commit - Closes #1368. * A refined approach towards grabbing and replacing infoclick placeholders with values, closes #1368. * Ensure that useMapService always evaluates to a boolean. Fix for 'new' API's loading of simpleMapConfig if no mapserviceBase is specified. * Bumped version across the project to reflect the latest changes. * Manually added CSS class definition for .material-icons: - For reasons unknown, the definition has disappeard recently. - We should look into this further, but to fix it as quickly as possible, I'm adding it manually for now. * v.3.13.4 * Turns out the solution in 6b6429a was the correct one: - According to the docs, adding the .material-icons class is exactly what has to be done. - I'm doing another commit on it thought, to reflect the official structure inside the class, as specified in https://fontsource.org/docs/getting-started/material-icons * Removed all references to the legacy 'shortcode' feature in FeatureInfo, also removed unused deps. * Removed legacy/unused plugins: - Draw - Measure - VTSearch * Latest package-lock * Used 'npx depcheck' to identify missing deps. Fixed by adding. * Migrated from 'magic' module resolving to relative paths, this will be needed to further migrate to e.g. Vite anyway, so it's good to fix it right away. * Version bump * Succesfully upgraded a couple of deps: - The upgrades here are verified to work - Notable change is the major version bump on ESlint and Prettier. There have been some new defaults, among which new default for https://prettier.io/docs/en/options.html\#trailing-commas caused some confusion. The team has decided to disable it in our project, hence the change in .prettierrc. - I also ran 'npx prettier -w .' so there are some minor changes to the formatting in various files. * Fixed what was necessary to upgrade react-number-format. Didn't have time to properly replace this (as we seem to use it solely for the thousands separator) as I suggested elsewhere. Nevertheless, closes #1207. * Upgraded IntroJS and deps to latest version. * Upgraded MUI's DataGrid to v6 * Major upgrade: PDFjs. * Added plugin-proposal-private-property-in-object to the list of dependencies in order to get rid of a warning from Babel * Finalized the migration to consolidated loading approach, first started in #682: - Ensured that the static approach (aka simpleMapConfig loading) works in the consolidated loading part of code - Merged simpleMapConfig and simpleLayersConfig into a new file. Added keys needed for consolidated parser. Removed legacy files. - This could still be rewritten to async/await rather than the current Promise callback hell way of doing things, but I leave it for now. * Removed 'experimentalNewApi' from appConfig * Rewrote initial loading to async/await, added new Error page: - I got rid of the nested promise callbacks, now it's all in one try/catch - A new error page is added. It's (hopefully) nice and clean. It also features a reload button that will attempt to reset the application's state by redirecting to '/'. Should this not work, there are more things to try out (parsing the documnent.location and removing searchParams manually). * Version bump * Much better placement of loading error box across different screen sizes. * Make it possible to have a clean appConfig.json by emulating default values for some required properties in index.js. * Version bump * Ensure that the default API path in Swagger leads to V2. * Typo * Added the 'Simple Edit Workflow' to edit plugin, closes #1377. * Version bump * Hotfix to 7decf9c, #1377: - Ensure that we auto-activate the modify tool if user goes backwards in the Simple Edit workflow. * Version bump * Get rid of warning about 'preset' not being part of active plugins: it's core nowadays, hence it can be hard-coded as active. * Bug fix: the 'missing plugins' message was not so silent after all. Fixed. Shows only if it detects something. * Deps bump * Removed unused keys from default appConfig * Removed unused dependency from hook deps array in Measurer. * This has grown pretty big since yesterday, time for an initial commit: - WIP so expect a lot of warnings - See #1360 for issue - See also the README.md in the plugin's dir for more info on configuration. * Now also passing down the coordinates of clicked point. * New approach towards setting layers' visibility. Taking a break for now though since I need to investigate some strange behaviour in LayerGroupItem related to #1252. * Added two comments about lines modified in #1304 to fix #1291 that don't do much. * Some progress once I gave up the sublayers functionality: - Toggeling a sublayer will toggle all sublayers under the same layer. This is a trade-off. - Some nice functionality added, such as the layer toggler, better listing including nice icon (from infoclick config), etc. * init commit, changed logic that prev removed drawerButtons * minor fix * Major additions: - UI revised - Quick toggle buttons for often accessed layers - and more… * Added the optional bgColor setter for features in MapClickViewer, closes #1385. * v3.13.10 * Revert "Revert "Merge pull request #1346 from hajkmap/feature/1316-PermanentDrawerOption"" This reverts commit 55b01ed. * v3.13.11 * Addded the CHANGELOG.md with some initial (incomplete) entries. * CHANGELOG additions * CHANGELOG.md is up-to-date with the current state in hstd-main. * Upgraded deps. * Corrected the UI, added info that shows when no features are returned. Other fixes. * Updated changelog * The QuickLayer toggle buttons now show both icon and caption. * Multiple additions: - Features that belong to the same layer (but different sublayers) are now shown next to each other. - The control whether the layer actually exists in OLMap or not happens outside the FeatureItem view. This means that the component could be simplified by removing unneccesary checks that were previously required. - UI changes, hopefully for the better. - Some preparations for sending the GetFeatureInfo for specific layer (i.e. auto-trigger MapClickViewer). This will however require more work and refactoring in MapClickModel. * Added a nice little snackbar that informs user to click in map to select a property. * Made it easier to toggle layer visibility by allowing click on the entire list item * Added a help dialog that explains how to use this tool. * Terminology change after dialog with reference group. * Info about #1403 in changelog * v3.13.12, see CHANGELOG.md for more info * QuickLayerToggleButtons correctly reflect the initial layer visibility state. * Better help desc, according to focus group. * Fix to stop propagation in the help dialog. * Added the Report Dialog: - For each property that got matched, users can now make a selection of layers that have been 'controlled' (in some way, depending on the procedure). - Layers with ticked checkboxes will now appear in a separate Dialog window, called Report Dialog. - From here, users will be able to select the text (I'll probably add some copy-to-clipboard soon) and paste into their reports/other systems. * Minor fixes * The Report dialog has been greatly enhanced with a copy-to-clipboard function that copies both as plain text and rich text (suitable for e.g. pasting into Word). * Typo * Updates in CHANGELOG * Added a script to ease deps install. * The Report dialog looks better, the list now has bullets too. * Removed the 360px width limit in MapClickViewer lists. Closes #1411. * Added note on #1411 to changelog. * v.3.13.13 * The `/ad/findCommonADGroupsForUsers` endpoint works again. Closes #1415. * v.3.13.14 * Made the layer ids visible in Admins layer manager list. * Initial changes required to expand this plugin with another view - Digital Plans: - As the requirements have changed a bit, I'm not making some refactoring. The plan is to expand the plugin with a new view that will show another list of properties, different from the list created from the initial request ('check layer'). - I'm not implementing the new view yet, as it's not really clear how we want to display it. But we're ready from now on. * Rough WIP: added Tabs to separate the check layer features from digital plan features. This will need refactoring, comming up soon. * Major refactoring after a meeting with the client: this way it'll be easier to maintain and expand in the future. Nothing new in the UI since the last commit. * Big commit with the following: - Completely rewritten the way that we render list of check layer items. In addition to visual changes, there's a new field available that allows users to write simple notations on each item, that will get transferred to the final report. - I've started the initial implementation of showing those notes in the final report. I'm not done yet though as I await response from the client regarding which form this should be presented in. - Speaking of response from client: it turns out that they'd want to use this tool to show another report that showcases which digital layers affect the clicked point. This led me to rewrite and add more parts to the plugin. The new concept is called Digital Plans and shows up as a second tab (next to the Check Layer items). The new Digital Plans check will become a part of the final report as well, but I'm awaiting feedback here too. * Preparations for the first Public Beta of PropertyChecker: - Cleaned up the report generator, ensured same output to different formats. - Removed some logs messages. - Other fixes. * Upgraded deps in Client and Backend * v3.13.15: First Public Beta of Property Checker * Fixes a bug where GetFeatureInfo used wrong resolution. * v3.13.16 * Tightened security in backend: if AD_LOOKUP_ACTIVE is 'false' but RESTRICT_ADMIN_ACCESS_TO_AD_GROUPS has a value, access to admin-only endpoints will be restricted (to everyone). * v3.13.17 * v3.13.17 * Avoid float values in z param in URL hash, closes #1422. * Added #1422 to the changelog. * Added an option to Admin that allows setting autofocus in Search field on app load, closes #1424. * v3.13.18 * Fix to #1257: ensure that even non-togglable groups are marked with bold font. Plus a minor change from 'style' to 'sx' in one element. * Bump to v3.13.19 * Upgraded deps, among those react-markdown, which required some work. Closes #1425. * Changes in changelog * Don't render tabs in LayerSwitcher if no layers are to be shown inside, closes #1431. * Support for the EPSG:5847 in Admin UI. Keep in mind that you still need to add appropriate projection definitions to each map config. * v3.13.20 * The tools list in Admin is now refreshed: only current tools are available, sorting is alphabetical. * WMSLayer's onImageError should also result in the load failed indicator in LayerSwitcher. * Sorting in PropertyChecker now takes layer's caption into account. * Show layer load error indicator in PropertyChecker's layers list, if loading failed. * Changelog * Merged two new PRs from upstream * Fix for #1439 and its LdapService: 'this' refers to something else than what could be expected when inside an instance of ActiveDirectory. Let's save and use a variable reference to the logger. * Added #1439 to the changelog * Backend: show 403 Forbidden rather than 500 if access was not allowed: - I created a custom error class, AccessError, in order to distinguish access errors from the rest in our handleStandardResponse(). - The Service will now send an AccessError if the reason is that the authenticated user lacks autorizaton to a certain resource. * Updated changelog * Updated deps in Client and Backend * Fixed some irritating whitespace formatting mismatches between current and older ESlint versions. * Prettier fixes in Backend too. * Cleanups in PropertyChecker to get rid of some warnings. * A whole lot of refactoring. The plugin is growing, I need to separate the views. * Important additions, implemented a first view of digital plans. Some work remains, such as adding checkboxes etc (as in the Check Layers view), the Report and so on. But it's a good start. * PropertyChecker: added an option to disable the Generate Report functionality. Needed when we want to release this tool to a broader public audience. * Major additions to PropertyChecker, main feature is the new Digital Plans view and correpsonding Report. * Replaced all hard-coded attribute names with values retrived from Admin. This will aid anyone wanting to adapt it into their own setup. * PropertyChecker: important improvment - clicks that'd give results from more than 1 property are disallowed. Also, marker feature is added only for the property layer, not digital plans layer. * Updated changelog for v3.13.22 * Warning fix * PropertyChecker: Fix to hide unneeded UI elements when enableDigitalPlansReport is false. * Missed two files in v3.13.22 * Prepared the v3.13.23 release. * Implemented auto-rotation (to an admin-specified value) for background layers. Closes #1451. * Release v3.13.24 * Added recent changes, merged from develop, to the changelog. * The reinstall dependencies script now also runs audit fix. * Updated deps, version number * Fixed missing keys in Docker's appConfig.json * Revert Halmstad-specific branding * Updated CHANGELOG to reflect recent merge --------- Co-authored-by: OlofSvahnVbg <svahnolof.vbg@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Documentation
.env. None of them is needed, you can safely use your current.envand let the Backend use its defaults.GET /mapconfig/delete/{map}is not implemented in V2 and replaced byDELETE /mapconfig/{map}.Check out the PR #1318 for a list of changes, including the new keys in
.env.Original issue
During development of #1210 we all agreed that the specifications that lay the foundation of our API implementations need an overhaul.
This issue is ment to document the changes. Related commits (and possible PRs) should link this issue.
The text was updated successfully, but these errors were encountered: