Making Swagger 508 Compliant

[Gray Achiu]

USPTO is using Swagger for API development.  It provides accurate documentation quickly and easily. This Swagger documentation will be used by both internal and external developers - does anyone have any experience/insight on what is required to ensure Swagger documentation is 508 compliant?

Gray Achiu - Open Data Project Management Lead - USPTO

[Jamal Mazrui]

I am also interested in this topic.  Can someone point me two some online Swagger documentation that I can examine?

 

Jamal

 

Jamal Mazrui
Deputy Director, Accessibility and Innovation Initiative
Federal Communications Commission
202.418.0069

--
You received this message because you are subscribed to the Google Groups "US Government APIs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to us-government-a...@googlegroups.com.
To post to this group, send email to us-govern...@googlegroups.com.
Visit this group at http://groups.google.com/group/us-government-apis.

[Goswami, Vijaykumar S]

http://swagger.io/

 

-Respectfully

Vijay S. Goswami

Solutions Architect

XFinion Inc.

U.S. Department of State | Bureau of Consular Affairs

gosw...@state.gov

(c) 301-801-4897

(bb) 571-482-0432

 

 

Achieving Innovation through Knowledge, Collaboration and Action

Any information in this transmission pertaining to U.S. citizens or legal permanent residents shall be considered confidential under the Privacy Act of 1974 [P.L. 93-579]. Any information in this transmission pertaining to the issuance or refusal of visas or permits to enter the United States shall be considered confidential under Section 222(f) of the Immigration and Nationality Act (INA) [8 USC Section 1202].  If you have received such information in error, do not review, retransmit, disclose, disseminate, use or take any action in reliance upon this information, and contact the sender as soon as possible. 

 

From: us-govern...@googlegroups.com [mailto:us-govern...@googlegroups.com] On Behalf Of Jamal Mazrui
Sent: Tuesday, March 10, 2015 10:21 AM
To: 'Gray Achiu'; us-govern...@googlegroups.com
Subject: RE: [Gov't APIs] Making Swagger 508 Compliant

 

I am also interested in this topic.  Can someone point me two some online Swagger documentation that I can examine?

 

Jamal

 

Jamal Mazrui
Deputy Director, Accessibility and Innovation Initiative
Federal Communications Commission
202.418.0069

From: us-govern...@googlegroups.com [http://redirect.state.sbu/?url=mailto:us-govern...@googlegroups.com] On Behalf Of Gray Achiu
Sent: Tuesday, March 10, 2015 9:46 AM
To: us-govern...@googlegroups.com
Subject: [Gov't APIs] Making Swagger 508 Compliant

 

USPTO is using Swagger for API development.  It provides accurate documentation quickly and easily. This Swagger documentation will be used by both internal and external developers - does anyone have any experience/insight on what is required to ensure Swagger documentation is 508 compliant?

 

Gray Achiu - Open Data Project Management Lead - USPTO

--
You received this message because you are subscribed to the Google Groups "US Government APIs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to us-government-a...@googlegroups.com.
To post to this group, send email to us-govern...@googlegroups.com.

Visit this group at http://redirect.state.sbu/?url=http://groups.google.com/group/us-government-apis.

--
You received this message because you are subscribed to the Google Groups "US Government APIs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to us-government-a...@googlegroups.com.
To post to this group, send email to us-govern...@googlegroups.com.

Visit this group at http://redirect.state.sbu/?url=http://groups.google.com/group/us-government-apis.

[Richard Bristow - XFB]

I took a quick look at the documentation it outputs. It's not 508 compliant, there are some contrast issues and the functionality isn't completely there. 

I can't tell you how much work it would take to make it output compliant HTML automatically, but if it was a static site, it wouldn't take much. 

Nick Bristow

18f Innovation Specialist

Nick.B...@gsa.gov

Visit this group at http://groups.google.com/group/us-government-apis.

[Barbara Scott - IEA]

Gary. Quentis Scott heads the GSA IT Disability branch. She can advise you on matters related to Secion 508 compliance. bas

On Tue, Mar 10, 2015 at 9:45 AM, Gray Achiu <gray...@gmail.com> wrote:

USPTO is using Swagger for API development.  It provides accurate documentation quickly and easily. This Swagger documentation will be used by both internal and external developers - does anyone have any experience/insight on what is required to ensure Swagger documentation is 508 compliant?

Gray Achiu - Open Data Project Management Lead - USPTO

--

You received this message because you are subscribed to the Google Groups "US Government APIs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to us-government-a...@googlegroups.com.
To post to this group, send email to us-govern...@googlegroups.com.
Visit this group at http://groups.google.com/group/us-government-apis.

--

Barbara Scott

Enterprise Architect GSA IT

202 501-2375

barbar...@gsa.gov

[Gray Achiu]

Thank you for pointing me in the right direction.  I'll provide a follow up on Swagger 508 after speaking with Quentis.

Best, Gray Achiu

[Gray Brooks]

Great question, Gray.  

I want to take a second back and reframe Nick's response, though, which I believe was specific to the instance at swagger.io, not to swagger in general.  

There's two questions, right?  Foremost at any one time is the accessibility of any one instance of Swagger in action.  For instance, the contrast issues will vary, depending on theming.  Notice, for example, three different Swagger implementations:  

• http://cfpb.github.io/api/hmda/console/
  
• https://discovery.gsa.gov/docs/
  
• http://developer.nrel.gov/docs/transportation/transportation-incentives-laws-v1/
  

Clearly, we should work to make sure that API documentation is made as usable and accessible as possible, so it'd be helpful to get some 508 tips and best practices specific to interactive documentation.  Nick and Quentis, it'd be great to get your thoughts on that.  

The second question is the how accessible any implementation of Swagger can be, which I think was the underlying question in the original post.  One thing to ensure is that the information available through interactive documentation should also be accessible through the rest of the API documentation.  A well-documented API will describe the endpoint and API calls clearly and simply in addition to providing interactive documentation.  Not that CFPB's outstanding HMDA api has interactive documentation but also a clear 'API basics' page.  Both provide access to the API and together combine to make a more accessible developer experience.  

Gray 

On Tuesday, March 10, 2015 at 11:27:54 AM UTC-4, Gray Achiu wrote:

Thank you for pointing me in the right direction.  I'll provide a follow up on Swagger 508 after speaking with Quentis.

Best, Gray Achiu

On Tue, Mar 10, 2015, 11:24 AM Barbara Scott - IEA <barbar...@gsa.gov> wrote:

Gary. Quentis Scott heads the GSA IT Disability branch. She can advise you on matters related to Secion 508 compliance. bas

On Tue, Mar 10, 2015 at 9:45 AM, Gray Achiu <gray...@gmail.com> wrote:

USPTO is using Swagger for API development.  It provides accurate documentation quickly and easily. This Swagger documentation will be used by both internal and external developers - does anyone have any experience/insight on what is required to ensure Swagger documentation is 508 compliant?

Gray Achiu - Open Data Project Management Lead - USPTO

--
You received this message because you are subscribed to the Google Groups "US Government APIs" group.

To unsubscribe from this group and stop receiving emails from it, send an email to us-government-apis+unsub...@googlegroups.com.
To post to this group, send email to us-government-apis@googlegroups.com.

Visit this group at http://groups.google.com/group/us-government-apis.

[Quentis Scott - IAT]

Hi Gary,

If I understand correct, Swagger is for API development.  But in your email, it states "what is required to ensure Swagger documentation is 508 compliant?"  So I'm a bit confused.  If Swagger is software, you should have collected the VPAT from the vendor.  The VPAT is the vendor self certification on how their product conforms to 508 standards.  If you are seeking compliance of documentation, you can find a flury of information on making documents accessible using Google search.  

The Section 508 Coordinator at the Department of Commerce - US Patent and Trademark Office is Joyce Miller - 571-272-5422 - joyce....@uspto.gov.  She will be able to assist you further and I have copied her on this email.

Sincerely,

--

Quentis A. Scott-Adams

Quentis Scott-Adams

GSA, Office of the Chief Information Officer

Section 508 Program Office

Washington, DC  20002

quenti...@gsa.gov

cell:  202-253-9748

Visit us on Chatter and post your Section 508 compliance questions!

[Quentis Scott - IAT]

Hi Gray,

You will need to ensure the API is Section 508 compliant.  More important to address is the final product or rather, the output to the user.

 

Section 508 technical standards, which provide guidance on what you must do to conform with the law, is located here.

I hope this is helpful.  

[Kin Lane]

It is great to see this conversation happen. I will crossync with the Github community for Swagger, so they are aware and can contribute.

I'd like to add one nuance to the conversation, make sure the group understands is that Swagger is an open specification, Swagger UI is one of the implementations with the specification that creates the interactive documentation at hand.

So efforts for 508 compliance needs to be on Swagger UI, and since there are a wave of other UI elements being deployed currently from Swagger, I will work to extend the thought process here to those new providers.

Swagger itself is a JSON specification, it would be like applying 508 compliance to an XML file. However the UI elements need 508 compliance applied. 

Kin Lane (API Evangelist)

kin...@gmail.com

@kinlane

--

apievangelist.com

apisjson.org

apicommons.org

apistrategyconference.com

--

To unsubscribe from this group and stop receiving emails from it, send an email to us-government-a...@googlegroups.com.
To post to this group, send email to us-govern...@googlegroups.com.

[resjwa...@gmail.com]

Hi everyone - looking at the latest swagger-ui codebase it does not appear to me that the UI is 508 compliant due to some interactive controls that show/hide content without ARIA markup, and that sort of thing. It seems that someone from 18F made some contrast adjustments and fixed a few labels, but my take on it is the controls themselves are not compliant.

Short of creating a custom swagger-UI skin, is there an effort to make these adjustments? It seems a lot of govt-related projects use swagger-ui, so it would be good to be 508 compliant. I'd be interested in helping, if there's an open-source-type of effort :)

Thank you!

joe