1

I have a backend API providing data for documentation in OpenAPI JSON format. This is how the API data looks right now:

{
    "openapi": "3.0.0",
    "info": {
        "title": "Express API docs :D",
        "version": "1.0.0",
        "description": "This is the docs I'm creating for the project and stuff",
        "license": {
            "name": "Licensed Under MIT",
            "url": "https://fakeurl.org/licenses/MIT.html"
        }
    },
    "servers": [
        {
            "url": "http://localhost:3000",
            "description": "Development server"
        }
    ],
    "paths": {
        "/api/contacts": {
            "get": {
                "summary": "get all contacts.",
                "responses": {
                    "200": {
                        "description": "All contacts retrieval successful"
                    }
                }
            },
            "post": {
                "summary": "Create a new contact",
                "responses": {
                    "201": {
                        "description": "Created a new contact",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "number": {
                                                    "type": "integer",
                                                    "description": "The user ID.",
                                                    "example": 0
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "description": "The user's name.",
                                                    "example": "Leanne Graham"
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "description": "The user's email.",
                                                    "example": "graham@gmail.com"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/:id": {
            "get": {
                "summary": "get a contact",
                "responses": {
                    "200": {
                        "description": "Single contact retrieval successful"
                    }
                }
            },
            "put": {
                "summary": "update a contact",
                "responses": {
                    "201": {
                        "description": "Updated a contact",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "number": {
                                                    "type": "integer",
                                                    "description": "The user ID.",
                                                    "example": 0
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "description": "The user's name.",
                                                    "example": "Leanne Graham"
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "description": "The user's email.",
                                                    "example": "graham@gmail.com"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "summary": "delete a contact",
                "responses": {
                    "200": {
                        "description": "Delete contact request successful"
                    }
                }
            }
        }
    },
    "components": {},
    "tags": []
}

I'm using stoplight/elements and React to create a frontend view which looks like this as of now:

Pic of webpage with API documentation

Since I'm using stoplight/elements, its code is pretty much like this as of now:

function App() {
  return (
    <div className="App">
      <p>Hello World!</p>
      <API
        apiDescriptionUrl={`http://localhost:5001/docs`}
        hideTryIt="true"
      />
    </div>
  );
}

export default App;

Now, I want to add a flow chart at the end of the overview page (the image above) like this:

Flow chart image. Please look at this for understanding

How can I do that? Is there any way so that the flow chart would be automatically generated (perhaps using React)? If not, and if the only way is to insert an image, how can I insert an image at the end?

Helen
  • 87,344
  • 17
  • 243
  • 314
Light Yagami
  • 961
  • 1
  • 9
  • 29
  • If you want the image to be inside the panel in which the API renders, you could add an image with JavaScript without any interaction with the API. As long as you can find an element in the existing panel that has an id, you can get the element and add the image. If there is not an id, you could use xpath to find an element and insert the image. – JustBeingHelpful Apr 11 '23 at 08:59
  • https://stackoverflow.com/questions/2735881/adding-images-to-an-html-document-with-javascript – JustBeingHelpful Apr 11 '23 at 08:59
  • The text in the image ("This is the docs I'm creating for the project and stuff" in the first image) comes from a text value from json. I can use this as Markdown and create some tables and different fonts. How can I create image there? – Light Yagami Apr 11 '23 at 09:09
  • Google Chrome > right click that text "This is the docs..." > select "Inspect" option > on the highlighted html, select "Copy" menu option > select "Copy full xpath" > the value of the xpath is now in your clipboard > now paste in the comment on StackOverflow ... What xpath does that give you? – JustBeingHelpful Apr 11 '23 at 09:21
  • Once you have the xpath, you can get the element like this and place the image there, but the image needs to be in a published path on the web server. https://coderwall.com/p/u2amea/javascript-get-element-by-xpath – JustBeingHelpful Apr 11 '23 at 09:38
  • Since Stoplight's Overview section displays the text from your OpenAPI `info.description` field, and the `description` fields support Markdown, you can embed the images by using Markdown syntax. [Example 1](https://stackoverflow.com/a/70010459/113116), [Example 2](https://stackoverflow.com/a/39929108/113116). Will that work for you? – Helen Apr 11 '23 at 09:50
  • @MacGyver Thanks for your help. I'm not thinking of keeping it as an image(I have to update it manually). I'm thinking of creating an svg or something to create a basic component of the 2nd image and use it to replicate to create similar picture. This sounds like a good option, but difficult. I'm not looking on what React libraries I can use to create the above flowchart? Any help in that? – Light Yagami Apr 11 '23 at 10:14
  • @Helen Thanks for your help. Please refer to the above comment. – Light Yagami Apr 11 '23 at 10:15
  • So your question is not "how to embed an image in Stoplight Elements" but "how to generate this kind of diagram automatically from an OpenAPI definition"? – Helen Apr 11 '23 at 11:26
  • @Helen Yes, more like that. Putting image would be my final option. – Light Yagami Apr 11 '23 at 13:50

0 Answers0