Document the Badge App REST API using Swagger/OpenAPI

[ejratl]

Some tools are starting to consume Swagger to perform automated tests of a REST API. Also, Swagger helps produce consistent and authoritative documentation. Investigate documenting the Badge App REST API using Swagger. Some reference URLs: http://swagger.io/getting-started/ https://github.com/richhollis/swagger-docs https://coderwall.com/p/bjk3pa/documenting-rails-based-rest-api-using-swagger-ui

[ejratl]

There is another nice tutorial here: http://idratherbewriting.com/pubapis_swagger/ swagger-docs is Swagger v1.2 only at this time. swagger-blocks covers both v1.2 and v2. See https://github.com/fotinakis/swagger-blocks/

There are options when documenting the API using Swagger/OpenAPI specification.

1. Manual - you can write and maintain the .json file which describes the API.
2. Generated - you can annotate your source and generate the .json file (using swagger-blocks).

This adds a fair bit of verbiage to the code base so I wanted to double check your comfort level with this amount of annotation, especially since the API is fairly simple at this point. (See the swagger-blocks README for an example.)

There is an additional choice of whether to integrate the swagger-ui (perhaps for staging and master only, not production) which provides a document viewer for the API specification.

[david-a-wheeler]

My usual leaning is toward generated interfaces, because that makes it more likely that the claimed interface actually matches the code. However, how much verbiage are we talking about in this case? Any idea?

[dankohn]

Our example is much simpler than the petstore example, so I support using swagger blocks.

https://github.com/fotinakis/swagger-blocks/#petscontroller

[david-a-wheeler]

I recommend against using an older project https://github.com/richhollis/swagger-docs, even though searching finds it readily, and it directly supports Rails. The problem is that this older project does not support Swagger/OpenAPI version2; they recommend swagger blocks instead for supporting the newer spec.

[david-a-wheeler]

We've recently received a few questions about how to access the badge data using an API. It'd be better if that API were documented... and if there's a problem, best to fix it now.

[david-a-wheeler]

Useful tutorial: https://www.sitepoint.com/do-the-right-thing-and-document-your-rails-api-with-swagger/

[david-a-wheeler]

Google's recommendations on APIs: https://cloud.google.com/apis/design/

[merkrafter]

Hi, I just wanted to know what the status of this issue is. It actually seems quite doable. Is it still relevant?

[david-a-wheeler]

Yes, it's definitely relevant. This one of those "good idea, but other things keep having a higher priority" issues.

If you'd be willing to do it, that'd be great!

This was proposed several years ago. The first step would be to identify & review the options. The swagger_blocks library was last updated in 2019 - which is a little while, but it's a tiny library that primarily depends on introspection, so it may be quite fine.

[merkrafter]

From what I could find out until now, a project called rswag seems most promising to me. Below I compared it to the other two projects being discussed earlier in this thread. Let me know if there is something else you'd like to know.

Generated swagger json file

• adds quite a bit of verbiage to source code (see effort estimations below)
• has potential to be more correct and up to date than manual approach because of the proximity to the source code

rswag

• support for OpenAPI 3.0 / swagger 2.0

Code health

• latest commit: 2020-08-21
• used by: 514
• forks: 223

effort estimation

• use gem rswag
• install generator: rails g rswag:install
• annotate code like this:

describe 'Blogs API' do
  path '/blogs' do
    post 'Creates a blog' do
      tags 'Blogs'
      consumes 'application/json'
      parameter name: :blog, in: :body, schema: {
        type: :object,
        properties: {
          title: { type: :string },
          content: { type: :string }
        },
        required: [ 'title', 'content' ]
      }

• run rake rswag:specs:swaggerize to generate json

Swagger::Blocks

• support for swagger 2.0; does not support swagger 1.2

Code health

• latest commit: 2019-09-26
• used by: 442
• forks: 83; none of them ahead of base (except 1 with 1 commit)
• owner still very active on GitHub -> can probably be contacted in serious cases
• can't judge code complexity, as I have no real Ruby experience

effort estimation

• use gem swagger-blocks
• annotate code like this:

swagger_path '/pets/{id}' do
    operation :get do
      key :summary, 'Find Pet by ID'
      key :description, 'Returns a single pet if the user has access'
      key :operationId, 'findPetById'
      key :tags, [
        'pet'
      ]
      parameter do
        key :name, :id
        key :in, :path
        key :description, 'ID of pet to fetch'
        key :required, true
        key :type, :integer
        key :format, :int64
      end
      ...

• run below to generate json

swagger_data = Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
File.open('swagger.json', 'w') { |file| file.write(swagger_data.to_json) }

swagger::Docs

• only swagger 1.2 support; does not support swagger 2.0

code health

• latest commit: 2017-01-19
• used by: 610
• forks: 151; none of them really active
• owner not active anymore

effort estimation

• use gem swagger-docs
• annotate code like this:

swagger_api :index do
  summary "Fetches all User items"
  notes "This lists all the active users"
  param :query, :page, :integer, :optional, "Page number"
  response :unauthorized
  response :not_acceptable
  response :requested_range_not_satisfiable
end

• run rake swagger:docs to generate json file

[david-a-wheeler]

Very interesting comparison, thank you for the report!

One problem with rswag is that it depends on rspec, which we intentionally do not use. So that brings in a bunch of stuff we otherwise would not use.

[david-a-wheeler]

I think we can skip swagger::Docs since it lacks 2.0 support.

[merkrafter]

When you mention rspec, do you refer to issue #80 or is there some more discussion about it? I'm asking because in that issue the argument against rspec is that it introduces another DSL that -- of course -- adds more complexity. On the other hand, even Swagger::Blocks seems to use some special syntax. I have to admit that my knowledge of Ruby is close to nil, so I might be wrong here.

[david-a-wheeler]

When you mention rspec, do you refer to issue #80 or is there some more discussion about it? I'm asking because in that issue the argument against rspec is that it introduces another DSL that -- of course -- adds more complexity. On the other hand, even Swagger::Blocks seems to use some special syntax. I have to admit that my knowledge of Ruby is close to nil, so I might be wrong here.

The issue isn't having a DSL. If a DSL provides real help, then that's good.

But RSpec brings in its collection of dependencies. Even if they are only development-time, there's an increased risk of version conflicts that can prevent updates, etc. It's not a deal-breaker, I'm sorry if I gave that impression. I was just trying to note pros and cons of a decision.

It think lacking 2.0 support for Swagger/OpenAPI 2.0 is a deal-breaker. If we're adding it, let's use current things :-).

[david-a-wheeler]

So if "support for current Swagger/OpenAPI" is a goal, and it seems like it should be, then rswag or Swagger::Blocks are the contenders.