Discussions
Unable to render endpoints that $ref a file that has already been $ref by another endpoint
We've recently started to use readme.io, and we've run into a problem. It seems that readme.io is unable to render endpoints that include a `parameters` section that `$ref` a file that has already been `$ref` before.
When viewing pages for any endpoint that matches the above criteria, the page will show the error code `ERR-JUAMVC` with a message: "This reference guide is currently experiencing difficulties and will be back online shortly."
A truncated version of our YML file:
```yaml
'/users/{id}':
put:
parameters:
$ref: common/users/uid.yml
requestBody:
required: true
content:
application/json:
$ref: common/users/update.yml
'/users/{id}/resources':
post:
parameters:
$ref: common/users/uid.yml
requestBody:
content:
application/json:
$ref: common/users/create_resources.yml
```
In the case above, the file `common/users/uid.yml` is referenced inside two endpoints. The page for `PUT /users/{id}` renders successfully, but `POST /users/{id}/resources`fails to do so.
We've tried to use `redocly` to render the same above YAML file and it works without issues, and `rdme openapi:validate` also returns no error.
Could you help check what could be the cause of this issue?
Posted by Vu Hoang 11 months ago
Support for SDK Documentation
Are you planning to add support for other types of API? like SDK documentation?
Posted by dd 11 months ago
Unable to upload images in markdown
Seems to be the same issue as <https://docs.readme.com/main/discuss/63f92bb42d5c42027e93b815>.
Steps to reproduce:
1. edit a page
2. insert image block
3. click "choose file" and select image
Details:
- The image is a 30KB / 1000x294 PNG, so it should be within the given size limits
- Browser JS console shows a `400` error when `POST`ing to `https://dash.readme.com/api/images/image-upload`. Inspecting the network response shows an error message `Image validation failed: user: Path 'user' is required.`
Is there a workaround?
Posted by Rebecca Weinberger 11 months ago
After updating OAS 2.0 to 3.0 , we are getting slug of null issue while updating readme.io through github? could you provide me the solution for this
build
Unknown error (Cannot read property 'slug' of null). <https://docs.readme.com/main/reference> and include the following link to your API log:
Posted by Desetti Chandrasekhar 11 months ago
Bug in rendering descriptions of Schema object that contain Reference Objects inside of allOf
There appears to be a bug in the way ReadMe is rendering descriptions of complex schemas that make use of `allOf` to combine multiple schema and reference objects.
The behavior that I'm seeing is the description within the most nested object is being used instead of the description from the top-level object.
Suppose your API spec is made up of two files, `sampleSpec.json` and `common.json`. Within those files you have the following sample schema objects defined:
```
# Within sampleSpec.json:
"Party": {
"title": "Party",
"description": "Information about a party",
"allOf": [
{
"$ref": "common.json#/components/schemas/NameAddress"
},
{
"type": "object",
"properties": {
"phone": {
"$ref": "common.json#/components/schemas/TelephoneNumber",
"description": "Phone number"
}
}
},
{
"type": "object",
"properties": {
"entityType": {
"$ref": "common.json#/components/schemas/EntityType"
}
"email": {
"type": "string",
"format": "email"
}
}
}
],
"type": "object"
}
# Within common.json:
"NameAddress": {
"title": "Name and Address",
"description": "Individual or business name with address",
"required": [
"name1"
],
"allOf": [
{
"properties": {
"name1": {
"$ref": "#/components/schemas/String64",
"description": "Name line 1"
},
"name2": {
"$ref": "#/components/schemas/String64",
"description": "Name line 2"
}
},
"type": "object"
},
{
"$ref": "#/components/schemas/Address"
}
],
"type": "object"
},
"Address": {
"title": "Address",
"description": "Postal address",
"required": [
"line1",
"city",
"country"
],
"properties": {
"line1": {
"type": "string",
"description": "Address line 1"
},
"line2": {
"type": "string",
"description": "Address line 2"
},
"line3": {
"type": "string",
"description": "Address line 3"
},
"city": {
"type": "string",
"description": "City"
},
"state": {
"type": "string",
"description": "State or province"
},
"postalCode": {
"type": "string",
"maxLength": 10,
"description": "Postal code"
},
"country": {
"oneOf": [
{
"$ref": "#/components/schemas/Iso3166CountryCode"
},
{
"type": "string",
"description": "Spelled-out country names -or- ISO 3166-2"
}
],
"description": "Country"
}
},
"type": "object"
},
```
When rendering the description for Party, I would expect to see _Information about a party_
However, ReadMe is rendering the text as _Postal address_.
This is in conflict with ReadMe's docs @ <https://docs.readme.com/main/docs/openapi-compatibility-chart#reference-object>:
_Prior to rendering your API documentation all $ref pointers are dereferenced. Additionally, as of OpenAPI 3.1, you can include summary and description fields in addition to the $ref pointer, which will override the summary and description fields of the referenced component. Everything else will be fully dereferenced._
Posted by Duc Trinh 11 months ago
Disable HTML URL Encoding of headers
Currently we have a token header that will contain a space
When this is added, the example request fills in that header space with an encoded %20 which breaks the sample request. This is the case with all of our docs, where none of the sample requests will work
Is there a way to disable HTML URL encoding for the "Try it" sample requests?
Posted by null 11 months ago
Support for Mermaid or other Markdown-generated images?
Hey Readme team,
Sometimes (more like all the time) when I'm documenting, I'd love to illustrate data flows or ideas with a diagram. Now I _could_ draw something up and insert a picture, but this adds load times, doesn't play nice with dark themes and generally adds bloat to my writing flow.
Now I think Github does a great job at supporting Mermaid - a way to describe a diagram in markdown that then gets rendered in the document. <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams>
I think this would be a nice addition to readme, too. What do you think?
Posted by Hannes Reinberger 12 months ago
Readme pages are not indexed by search engine.
We recently launched our website and discovered that none of our published articles are searchable by Google. This is because there is no sitemap available for readme pages, so Google won't index them. Our temporary solution is to manually create and update a sitemap.xml every time a new article is added, but this is very cumbersome.
Have you experienced the same problem? Is there a workaround for it?
Posted by Andrei 12 months ago
Please add option to set light/dark theme to Same as System on iPhones when using Safari browser
Currently it is not possible to set theme to Same as System on iPhones when using Safari browser.
On Android phones you can press and hold theme icon button and there will be "Same as System" option.
Unfortunately the option does not show up when using iPhone Safari browser. Please fix it! :)
Posted by He-man Trousers 12 months ago
Are you planning to include Chat GPT capabilities to generate answers based on an existing documentation in Readme?
We have extensive product documentation on Readme and would love to learn how we can potentially use Chat GPT to generate answers for our customers and customer support agents.
Posted by Pamela Alvarez 12 months ago