As a 3rd-Party integrator I would like to view Swagger documentation for Serge backend

IanMayo commented 1 month ago

Through July a university researcher is going to implement 3rd party integration with the Serge backend.

I have given him the URLs he needs to interact with.

But, i would be better for all if the backend APIs were documented with OpenAPI/Swagger.

It should also be possible for people to play with test-driving the API from interactive web-pages.

So, could we please:

Add OpenAPI comments to the routes defined in the server (this would prob also include the Couchdb/PouchDb providers
Add build step to build OpenAPI documentation
Add serve-openapi command to just server the OpenAPI docs (for review)
Modify start command to server the OpenAPI docs (for developing 3rd party integration)

I don't mind contributing with the descriptive content, once the bulk of the routes are documented.

IanMayo commented 2 weeks ago

Fixed in #2987

IanMayo commented 1 week ago

@lilitkarapetyan - I've just had a play with this, but couldn't send in new messages.

Here is what I did:

checked out develop
ran yarn install
ran yarn develop
(two serge tabs opened 8080, and 3000, together with Story book)
open Serge instance on port 3000
enter admin page
open REST API
go back to player UI,
login as red player on this wargame: wargame-lw7k3gk3
send a new mapping message in PUT to the REST API for this wargame (I took a copy of the first whole mapping message (not a delta message) in the SQLite database, and trimmed it down to just one feature)
with the DevTools network tab open, the message timed out

On investigation, I see that while I was running the instance of Serge on port 3000, when I opened the REST tab, it opened on port 8080 (http://localhost:8080/api-docs/). Is that right?

Could you help me get to a point where I can send in a anew mapping message via Swagger?

lilitkarapetyan commented 1 week ago

On investigation, I see that while I was running the instance of Serge on port 3000, when I opened the REST tab, it opened on port 8080 (http://localhost:8080/api-docs/). Is that right?

Yes it's works on the server

IanMayo commented 1 week ago

On investigation, I see that while I was running the instance of Serge on port 3000, when I opened the REST tab, it opened on port 8080 (http://localhost:8080/api-docs/). Is that right?

Yes it's works on the server

In that case, I don't know why I couldn't send a new mapping message via Swagger. Could you investigate please?

Note: I could see in the database that anew message had not been received. Here is the Network tab:

lilitkarapetyan commented 1 week ago

In that case, I don't know why I couldn't send a new mapping message via Swagger. Could you investigate please?

Yes I will investigate it

lilitkarapetyan commented 1 week ago

In that case, I don't know why I couldn't send a new mapping message via Swagger. Could you investigate please? https://gyazo.com/96694bdf90769ff2458ccb3484cdfbb0 You can try with this data wargame: wargame-lw7k3gk3,
Request body

{
"_id": "2024-07-10T12:41:05.987Za",
"messageType": "MappingMessage",
"details": {
"channel": "core-mapping",
"from": {
"force": "Red",
"forceColor": "#F00",
"iconURL": ""
},
"timestamp": "2024-07-10T12:41:05.987Z",
"turnNumber": 1
},
"featureCollection": {
"features": [
{
"geometry": {
"coordinates": [
[
[
-0.03167616558306463,
51.50940207305993
],
[
-0.03167616558306463,
51.49266769548318
],
[
0.03011008273324478,
51.49266769548318
],
[
0.03011008273324478,
51.50940207305993
],
[
-0.03167616558306463,
51.50940207305993
]
]
],
"type": "Polygon"
},
"properties": {
"_type": "CoreRenderer",
"color": "#f00",
"force": "f-red",
"id": "bb",
"important": "Yes",
"label": "Barrier",
"phase": "planning",
"turn": 1
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
-0.1316761655830646,
51.52940207305993
],
[
-0.2316761655830646,
51.49266769548318
],
[
0.03011008273324478,
51.53266769548318
]
]
],
"type": "Polygon"
},
"properties": {
"_type": "CoreRenderer",
"color": "#f00",
"force": "f-red",
"id": "ba",
"important": "Yes",
"label": "START LINE",
"phase": "planning",
"turn": 1
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
-0.07929841834678086,
51.497669733260125
],
"type": "Point"
},
"properties": {
"_type": "MilSymRenderer",
"category": "Civilian",
"force": "f-red",
"health": "90",
"id": "aa",
"label": "Headquarters Building",
"phase": "planning",
"sidc": "SFG-UCI----D",
"size": "M",
"turn": 1
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
-0.07929841834678096,
51.50966973326012
],
"type": "Point"
},
"properties": {
"_type": "MilSymRenderer",
"category": "Civilian",
"force": "f-red",
"health": 100,
"id": "ab",
"label": "Military Tailor",
"phase": "planning",
"sidc": "SFG-UCI----D",
"size": "M",
"turn": 1
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
-0.08239746093750001,
51.550818454754385
],
"type": "Point"
},
"properties": {
"_externalType": "Text",
"_type": "CoreRenderer",
"category": "Civilian",
"color": "#3dd0ff",
"fontSize": 14,
"force": "f-blue",
"id": 309,
"label": "some text field",
"padding": 0,
"phase": "planning",
"turn": 1
},
"type": "Feature"
},
{
"type": "Feature",
"properties": {
"_type": "CoreRenderer",
"_externalType": "Text",
"fontSize": 14,
"padding": 0,
"id": 233,
"phase": "adjudication",
"label": "some text goes here",
"turn": 1,
"force": "f-blue",
"category": "Civilian",
"color": "#3dd0ff",
"important": "Yes"
},
"geometry": {
"coordinates": [
-0.08102416992187501,
51.576642811561605
],
"type": "Point"
}
},
{
"type": "Feature",
"properties": {
"_type": "MilSymRenderer",
"sidc": "SFG-UCI----D",
"size": "M",
"health": 100,
"id": 277,
"phase": "adjudication",
"label": "Red",
"turn": 1,
"force": "f-red",
"category": "Civilian",
"color": "#F00"
},
"geometry": {
"coordinates": [
0.06660461425781251,
51.632083558391066
],
"type": "Point"
}
},
{
"type": "Feature",
"properties": {
"_type": "MilSymRenderer",
"sidc": "SFG-UCI----D",
"size": "M",
"health": 100,
"id": 390,
"phase": "adjudication",
"label": "Red",
"turn": 1,
"force": "f-red",
"category": "Civilian",
"color": "#F00"
},
"geometry": {
"coordinates": [
0.1792144775390625,
51.615884803202704
],
"type": "Point"
}
}
],
"type": "FeatureCollection"
}
}

IanMayo commented 1 week ago

Aah, so was the issue because the _id was missing?

(yes - it looks like it was)

IanMayo commented 1 week ago

Close. Check for id in put recorded in #2994

serge-web / serge

As a 3rd-Party integrator I would like to view Swagger documentation for Serge backend #2986