Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add reference links to api docs #1415

Merged
merged 4 commits into from
Sep 15, 2020
Merged

Conversation

CarsonCook
Copy link
Contributor

Signed-off-by: Carson Cook carson.cook@ibm.com

Your checklist for this pull request

Using master because this API documentation is for the current release.

Description (including links to related git issues)

Resolve #537. Adds reference links to generated API swagger files, displayed by petstore.swagger.io. Example here.

Signed-off-by: Carson Cook <carson.cook@ibm.com>
@CarsonCook CarsonCook requested a review from nannanli September 14, 2020 17:23
Signed-off-by: nannanli <nannanli@cn.ibm.com>
Signed-off-by: nannanli <nannanli@cn.ibm.com>
@BrandonJenkins14
Copy link
Contributor

@CarsonCook I like the idea to add Swagger doc to the site. However, this way of adding it doesn't seem to work (404s on the links). When you add definitions to pages.json file, it expects that you're linking to a resource in the site (a markdown file, for example.)

A couple of options that would definitely work:

  • Create a new .md page that simply has links or buttons on it, which link to these external Swagger sites.
  • Add HTML files for the Swagger site directly to the .vuepress/public folder. Then, you can link to them from other areas of the site. (you'd have to manually refresh the files as needed).

With those approaches, there won't be separate entries in the TOC for each. I'm not sure if it's possible to have TOC text that links out to external sites. @Roavill2 might know

@CarsonCook
Copy link
Contributor Author

@BrandonJenkins14 @nannanli fixed this up for me.

Copy link
Member

@nannanli nannanli left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great!

@nannanli
Copy link
Member

@BrandonJenkins14 External links seem to be unsupported in the nav. I chose the option 1 that you suggested by creating new md files contains links and buttons. : )

@nannanli nannanli merged commit 84fad4d into master Sep 15, 2020
@nannanli nannanli deleted the carsoncook/gh537/apiDocumentation branch September 15, 2020 17:25
@BrandonJenkins14
Copy link
Contributor

@nannanli I checked the Vuepress doc and it actually does seem possible to do external nav links. Does this mean anything to you in terms of what's causing the 404?

"Outbound links automatically get target="_blank" rel="noopener noreferrer". You can offer target and rel to customize the attributes. Setting rel: false as will disable the rel attribute for a link:"

https://vuepress.vuejs.org/theme/default-theme-config.html#navbar-links

That being said, I think this new approach is good. Up to you if you want to go back and try this or not.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[NPS] Learn what services/APIs are available on Zowe
3 participants