apiaryio / apiblueprint.org Goto Github PK

View Code? Open in Web Editor NEW

19.0 11.0 41.0 537 KB

API Blueprint Website

Home Page: https://apiblueprint.org/

License: MIT License

Ruby 11.57% JavaScript 6.78% HTML 31.31% CSS 50.20% SCSS 0.15%

apiblueprint.org's Introduction

API Blueprint Website

Usage

To be able to build and view the website locally, you will first need to install its dependencies:

$ bundle install

Preview Website

Using middleman, you can run a development server which will live-build the API Blueprint website.

$ bundle exec rake

Adding a new tool

Open the file data/tools.yaml and add a new entry for your tool.

$ cat << 'EOF' >> data/tools.yaml
- name: Hyperdrive
  summary: Hyperdrive allows you to build Swift applications that can evolve at run-time powered by API Blueprint.
  url: https://github.com/the-hypermedia-project/Hyperdrive
  tags:
    - client
EOF

Deployment

Circle CI will automatically deploy any changes made to master directly to GitHub pages.

apiblueprint.org's People

Contributors

Stargazers

Watchers

apiblueprint.org's Issues

Tools section broken

The tools section worked just fine last week, but now it does not contain any tags except Tools and doesn't contain any tool.

This bug has been reproduced under Chrome OSX as well as Firefox Ubuntu.

Could it be because of a format error here :

tools.yaml

name: doc-proxy
  summary: Node server to generate documentation.md file for all the endpoints supported by your server
  url: https://github.com/sandeep89/doc-proxy
  tags:[]

There is no space between the tags variable and its value.

Add a "fork" or "edit" page button to the bottom of pages

This provides a good way for a user to easily edit or propose changes to the source of the website. If they for example find a typo, clicking the button at the bottom will allow them to easily jump to the source of the specific page on GitHub.

A good example of this can be found at https://guides.cocoapods.org/making/making-a-cocoapod.html

Here's screenshots:

And on hover:

H1 and Permalinks

In my opinion it doesn't make much sense to provide permalinks for the topmost/H1 heading. Here it's all right: https://apiblueprint.org/documentation/tutorial.html, I can't see permalink with "API Blueprint Tutorial". But here https://apiblueprint.org/support.html there is a permalink for "Getting Help".

Enable CORS for api.apiblueprint.org

Pretty please?

link to Slack doesn't work

the link to Slack channel doesn't work. We should probably remove the link at all.

URL parameters added as query string parameters

In a sample API, I have an endpoint as:

The console opened for the first time shows the following URL:
http://private-7775c-testblueprint4.apiary-mock.com/questions/id

However, on specifying a value of Id under URL parameters, the URL changes to:
http://private-7775c-testblueprint4.apiary-mock.com/questions/234?id=234

The Id is appended twice as shown, which sends an incorrect request.

Mobile menu z-index bug

Wrong z-index on mobile

Official website defined DOCTYPE twice

The tutorial webpage seems to be including a DOCTYPE and html body several times. Seems like other every page is having the same issue, but I only checked a few.

<div class="col-md-9 text" role="main">
  <h2>API Blueprint Tutorial</h2>
  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
  <html><body>
  <p>Welcome to an API Blueprint Tutorial! This tutorial will take you through the basics of the API Blueprint language. We’re going to build an API blueprint

I discovered that by trying to crawl the website (to submit a PR to incorporate DocSearch to the doc). As it's invalid HTML markup, it made the HTML parser fail :)

Implement content search on documentation section

Better Page Titles

There are very simple title tags, e.g. <title>Support</title>. We should provide at least something like <title>Support | API Blueprint</title>.

Brackets in action

Let's assume endpoint and action

## Avatar [/me/avatar]
### New (update) avatar [POST]

this won't show in rendered documentation unless we remove the brackets.

## Avatar [/me/avatar]
### New update avatar [POST]

Sorry if that is a wrong repository to file an issue of that kind.

Double-encoding of url query parameters

In our apiary.io documentation http://docs.g2crowdapi.apiary.io/# we have one endpoint defined as such: /v1/products{?filter%5Bquery%5D,page%5Bnumber%5D,page%5Bsize%5D}

The problem is that when testing the endpoint in the console, the query parameters are encoded again which in turn submits a different request than desired.

Strange coloring of code examples

Add API Blueprint examples

The content found at https://github.com/apiaryio/api-blueprint/tree/master/examples

Improve tooling search

The current tooling search implementation is extremely naive.

Meta documentation

For a documentation standard, it sure was incredibly difficult to figure out the spec. (Your documentation is limited, and the GitHub interface was clunky as it overrides your files with MD previews which make it hard to read).

I would be interested in contributing to an initiative to build out the documentation more. Unfortunately I don't have the time/energy to lead that initiative, and I'm sure it's on a roadmap somewhere for you, but making it public may be worthwhile.

Side note, there's also some decent discussion at thoughtbot/guides#365 right now, and while APIary and APIBlueprint have some current shortcomings, I think it would be worthwhile for consideration into that discussion. I believe the current spec of choice is JSONapi.

Permalinks to Tooling Filters

Just wrote this to a person:

There are also other things to make your work in editors easier, check out https://apiblueprint.org/tools.html and click on the "Editors" filter. You might find them useful.

Direct link would be nice.

Tool Apib::MockServer doesn't exist anymore

This link on your mock servers page seems to not exist anymore. It was a mock server. I looked on the page of the group who owned the tool, and they seem to have completely deleted it. I tried looking for a tool with a similar name on GitHub and still didn't find it.

Add analytics

Would be great if we tracked page views for apiblueprint.org somewhere.

I think Google Analytics should be used according to documentation.

Tools Section - Cursor Indicates the Whole Area Is Clickable

Only tool title is clickable tough.

apiaryio / apiblueprint.org Goto Github PK

apiblueprint.org's Introduction

API Blueprint Website

Usage

Preview Website

Adding a new tool

Deployment

apiblueprint.org's People

Contributors

Stargazers

Watchers

Forkers

apiblueprint.org's Issues

Recommend Projects

Recommend Topics

Recommend Org