Allow markdown docs to be inserted in the generated blueprint

[petrbela]

So, we have this idea for the ideal workflow:

1. Write your request specs
2. Run your request specs and the whole apib file will be generated for you

There are two things missing to get to this state:

• copy markdown docs to the generated txt (or better .md)
• concat generated files to one apib file (will open another issue)

I can imagine the docs would either be in the source file (controller) or spec file. I'd probably go with the spec file as it will keep the information in one place, and also implementation will be easier.

The gem should copy the markdown docs from comments and place them in the generated file.

# Arena represents a combat room.
#
# Attributes:
#
# - `name` - arena name
# - `owner` - user who created the arena
describe 'Arenas Requests' do

  # Fetch information about an arena.
  describe 'GET /v1/arenas/{id}' do
    it 'responds with the requested arena' do
      arena = create :arena, foursquare_id: '5104'
      get v1_arena_path(arena)

      response.status.should eq(200)
    end
  end

end

Would generate

# Group Arenas
Arena represents a combat room.

Attributes:

- `name` - arena name
- `owner` - user who created the arena

## GET /v1/arenas/{id}
Fetch information about an arena.

+ Response 200 (application/json)

    {
      "arena": {
        "id": "4e9dbbc2-830b-41a9-b7db-9987735a0b2a",
        "name": "Clinton St. Baking Co. & Restaurant",
        "latitude": 40.721294,
        "longitude": -73.983994,
        "foursquare_id": "5104"
      }
    }

[matteodepalo]

Sorry for responding late. This seems like a great idea, however I don't have time currently to develop it. If you want to take a stab at it I would gladly merge it.

[petrbela]

I've actually already started, will send a pull request when it gets usable by public.

Petr Bela

On Saturday, October 12, 2013 at 8:50 PM, Matteo Depalo wrote:

Sorry for responding late. This seems like a great idea, however I don't have time currently to develop it. If you want to take a stab at it I would gladly merge it.

—
Reply to this email directly or view it on GitHub (#8 (comment)).

[kpgdev]

this is exactly what i need too..... anything i can do to help, code, test?

[petrbela]

Sorry this took a bit longer than expected. I decided to put the docs in the source files (as opposed to specs) as that's where docs usually go. I just pushed a branch to petrbela/rspec_api_blueprint#feat/markdown-docs -- @kpgdev can you take a look if it solves your problem, and post feedback on #9?