edent
commented
7 years ago Thanks @benh-gds - this looks like a great candidate for us. We'll start to look into this now.
Closed benh-gds closed 5 years ago
edent
commented
7 years ago Thanks @benh-gds - this looks like a great candidate for us. We'll start to look into this now.
jystewart
commented
7 years ago The Swagger spec has been renamed to be the OpenAPI spec - https://github.com/OAI/OpenAPI-Specification - which is what we should use. As I understand it Swagger should now be considered as a set of tools for working with the OpenAPI spec. The separation is important as our Open Standards focus should be on the standard by which the information is recorded/conveyed, and not on the tooling or processes that produce it.
OpenAPI is up to version 2.0. Work is underway on 3.0 but it's not clear (from my very brief exploration) how close that is or what changes it introduces. It would be good to have a clear picture of that so we can focus our review.
I know that teams in GDS and Companies House (who have a fork of swaggerly) have been working with Swagger and/or OpenAPI. There have also been ad-hoc conversations with other government teams but it'd be good to solicit more opinions from them here.
benh-gds
commented
7 years ago Hi James,
Thanks for clarifying this - yes, I should have said the OpenAPI standard, rather than "Swagger".
Thanks, Ben
On 20 December 2016 at 09:31, James Stewart notifications@github.com wrote:
The Swagger spec has been renamed to be the OpenAPI spec - https://github.com/OAI/OpenAPI-Specification - which is what we should use. As I understand it Swagger should now be considered as a set of tools for working with the OpenAPI spec. The separation is important as our Open Standards focus should be on the standard by which the information is recorded/conveyed, and not on the tooling or processes that produce it.
OpenAPI is up to version 2.0. Work is underway on 3.0 but it's not clear (from my very brief exploration) how close that is or what changes it introduces. It would be good to have a clear picture of that so we can focus our review.
I know that teams in GDS and Companies House (who have a fork of swaggerly https://github.com/companieshouse/swaggerly) have been working with Swagger and/or OpenAPI. There have also been ad-hoc conversations with other government teams but it'd be good to solicit more opinions from them here.
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/alphagov/tech-and-data-standards/issues/31#issuecomment-268196505, or mute the thread https://github.com/notifications/unsubscribe-auth/ASwmPm9ENcaa_N8UYB8eauFaTDp7UfECks5rJ6CGgaJpZM4LOXkU .
edent
commented
7 years ago I've updated the issue to reflect that it's OpenAPI that we wish to evaluate.
OAI 3.0 is currently being designed. As this will be a breaking change with 2.x, I think we should focus our evaluation on 3. See https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next
Some further reading at https://www.infoq.com/articles/open-api-initiative-update
edent
commented
7 years ago To address some concerns that people have raised with me offline.
edent
commented
7 years ago We have some research from @RosalieDM around this. Will share in public once suitably redacted.
edent
commented
7 years ago Some previous thoughts from last year https://governmentasaplatform.blog.gov.uk/2016/01/14/improving-developer-documentation/
edent
commented
7 years ago Presentation given to MoJ about the research we've done on the need for good documentation.
edent
commented
7 years ago This is what our discovery around user needs found. Not all of this is directly relevant to a documentation standard, but provides several useful pieces of evidence.
This research was conducted on internal and external users, with various levels of experience.
These are the needs developers and tech archs have when it comes to API documentation.
Each point contains ideas on how to meet these needs (all put forward by developers and tech archs themselves).
Most user docs are aimed at the average user, with beginners directed to tutorials/training and advanced users to forums. So there is the issue of what knowledge the average user is presumed to have (and therefore omitted).
Is this true? A lot of API documentation is created using a flat file CMS, and these don't tend to have a built-in search function. The workaround has been to put all the content onto a single page, so the user can use Control F to search. If it were possible to search the content using a better Search than the default flat file CMS's, would users use that instead/in addition to Control F?
edent
commented
7 years ago Looping @timblair into the conversation as this will affect APIs that he manages.
timblair
commented
7 years ago Looks like a preview release of v3 of the OAI spec is due at the end of February.
simon-cutts
commented
7 years ago From our perspective in DVSA, documenting API's in standard format is a must. Initially we settled upon RAML because it seemed to offer more features than Swagger. Our view has now switched to OpenAPI because the feature set has caught up with RAML, but more importantly, OpenAPI has wider adoption. I have a clunky SOA background where people would be shot if they did not have a service contract in the form of a SOAP WSDL. So in, in short, +1 for OpenAPI
Lawrence-G
commented
7 years ago As part of our evaluation of OpenAPI these are the assessment questions and answers.
OpenAPI Specification v2.0 (we anticipate most answers will also apply V3.0 ) *previosly known as Swagger
Q. Does the formal specification address and facilitate interoperability between public administrations?
Yes A standardised documentation format for describing REST APIs produced in public administrations would promote consistency in APIs. This would be achieved by making the documentation easier to work with, to maintain and to share. It would also allow common tools to be used for working with and maintaining APIs
Q. Does the formal specification address and facilitate the development of information or IT systems in government?
Yes This standard Supports the development of RESTful APIs.
Q. Are the functional and non-functional requirements for the use and implementation of the formal specification appropriately detailed?
Yes All requirement are specified in the standard specification
Q. Is the formal specification applicable and extensible for implementations in different domains?
Yes The standard is applicable to any domain where REST APIs are used
Q. Is the formal specification largely independent from products of single providers (either open source or proprietary)?
Yes Not bound to a single provider
Q. Is the formal specification largely independent from specific platforms?
Yes OpenAPI Aims to be a language-agnostic interface to REST APIs
Q. Has the standard been written such that its realisation can be/is demonstrated using more than one technology (e.g. XML and JSON)?
Yes File format is JSON and YAML for specification files.
Q. Has the formal specification been sufficiently developed and in existence for a period to overcome most of its initial problems?
Yes Development started in 2010. now at V2.0. V.3.0 is due for publication in Feb 2017
Q. Are there existing or planned mechanisms to assess conformity of the implementations of the formal specification (e.g. conformity tests, certifications, plugfests etc)?
Yes The swagger editor can be used to validate OpenAPI content The Swagger site has these tools
Q. Has the formal specification sufficient detail, consistency and completeness for the use and development of products?
Yes The specification has been used in documenting numerous APIs
Q. Does the formal specification provide available implementation guidelines and documentation for the implementation of products?
Yes The standards wiki contains this information - https://github.com/OAI/OpenAPI-Specification/wiki
Q. Does the formal specification provide a reference (or open source) implementation?
Yes There is an example implementation, an interactive UI http://petstore.swagger.io/
Q. Does the formal specification address backwards compatibility with previous versions? Migration guides for versions are available https://github.com/OAI/OpenAPI-Specification/wiki/1.2-transition
Q. Have the underlying technologies for implementing the formal specification been proven, stable and clearly defined?
Yes All the underlying technologies are widely used and proven e.g JSON HTML XML
Q. Is information on the terms and policies for the establishment and operation of the standardisation organisation publicly available?
Yes
see - https://www.openapis.org/participate/how-to-contribute/governance
Q.Is participation in the creation process of the formal specification open to all relevant stakeholders (e.g. organisations, companies or individuals)?
Yes - see this post The Technical Developer Community is open to any developer, end user or subject matter expert that chooses to participate in the activities of OAI (Open API Initiative)
Q. Is information on the standardisation process publicly available? Yes https://www.openapis.org/participate/how-to-contribute/governance
Q. Information on the decision making process for approving formal specifications is publicly available?
Yes https://www.openapis.org/participate/how-to-contribute/governance
Q. Are the formal specifications approved in a decision making process which aims at reaching consensus?
Yes https://www.openapis.org/participate/how-to-contribute/governance “The intention is for the OAI to operate by consensus. However, if consensus cannot be achieved, the Business Governance Board shall vote on a decision. “
Q. Are the formal specifications reviewed using a formal review process with all relevant external stakeholders (e.g. public consultation)?
Yes Review on GitHub by voting on issues and pull requests using reaction function
Q. All relevant stakeholders can formally appeal or raise objections to the development and approval of formal specifications?
Yes Through the Technical Oversight Board https://www.openapis.org/participate/how-to-contribute/governance#TDC
Q. Relevant documentation of the development and approval process of formal specifications is publicly available (e.g. preliminary results, committee meeting notes)?
Yes Through GitHub - “TDC strives to communicate through issues and pull requests, we’re all volunteers that steal time to work on OpenAPI. Sometimes it’s faster to have an hour long conference call, which we do every couple of weeks. In addition, we use the OAI’s Slack team to raise attention to questions or suggestions when GitHub notifications don’t get the job done. The changes proposed by a sub-issue in a meta issue result in a pull-request (PR), and that PR is then voted on by using a reaction on the issue.” TDC Technical Developer Community
Q. Is the documentation of the formal specification publicly available for implementation and use at zero or low cost?
Yes https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
Q. Is the documentation of the IPR for formal specifications publicly available (is there a clear and complete set of licence terms)?
Yes Documentation - Apache License, Version 2.0 - ( note specification and documentation are equivalent for OpenAPI )
Q. Is the formal specification licensed on a royalty-free basis? Yes Apache License, Version 2.0 - Grants a “worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
Q. Has the formal specification been used for different implementations by different vendors/suppliers?
Yes The specification is widely used by API developers and the are a number of tools that can render and parse OpenAPI specification document.
Q. Has the formal specification been used in different industries, business sectors or functions?
Yes Organisations from a number of sectors use and contribute to the specification - Contributing members - https://www.openapis.org/membership/members
Q. Has interoperability been demonstrated across different implementations by different vendors/suppliers?
Yes Several vendors supply tools to work with the specification when building APIs
Q. Do the products that implement the formal specification have a significant market share of adoption?
Yes Thousands of API’s are using the specification
Q. Do the products that implement the formal specification target a broad spectrum of end-uses?
Yes Not tied to a particular product or end user group.
Q. Has the formal specification a strong support from different interest groups?
Yes - see members list.
Q. Is there evidence that the adoption of the formal specification supports improving efficiency and effectiveness of organisational process?
Yes The specification avoids errors in documentation that can then lead to APIs not behaving as expected.
Q. Is there evidence that the adoption of the formal specification makes it easier to migrate between different solutions from different providers?
Yes Spec is applicable to APIs and tools from any provider.
Q. Is there evidence that the adoption of the formal specification positively impacts the environment?
Not applicable.
Q. Is there evidence that the adoption of the formal specification positively impacts financial costs?
Yes It should do as errors in docs and no API documentation costs time. API documentation saves developer time when maintaining or building on existing APIs Developer time is expensive but it will be difficult to put a figure on the cost.
Q. Is there evidence that the adoption of the formal specification positively impacts security?
Yes
Though not strictly concerned with security It is anticipated that the improving documentation will make it simpler to analyse the security of an API
The specification supports authorisations schemes e.g. OAuth2.
Q. Is there evidence that the adoption of the formal specification can be implemented alongside enterprise security technologies?
Yes OpenAPI specification supports three authorisation schemes - basic authentication, API key and OAuth2.
Q. Is there evidence that the adoption of the formal specification positively impacts privacy?
No Probably no impact on privacy
Q. Is the formal specification largely compatible with related (not alternative) formal specifications in the same area of application?
Yes OpenAPI Specification is language-agnostic. It is also extensible into new technologies and protocols beyond HTTP
Q. Is there evidence that the adoption of the formal specification positively impacts the accessibility and inclusion?
Not applicable
Q. Does the formal specification have a defined maintenance organisation?
Yes
Q. Does the maintenance organisation for the formal specification have sufficient finances and resources to be sure of freedom from short- to medium-term threats?
Yes Is a Linux Foundation Collaborative Project independently funded software project. The Linux Foundation shall have custody of and final authority over the usage of any fees, funds and other cash receipts. Members of the initiative include Google, Adobe, IBM, PayPal, Microsoft, which indicates a security in resources for the foreseeable future.
Q. Does the maintenance organisation have a public statement on intention to transfer responsibility for maintenance of the formal specification if the organisation were no longer able to continue?
No None that we have found, though it is assumed this would be through the Linux Foundation
Q. Does the formal specification have a defined maintenance and support process?
Yes Support is via GitHub Overseen by Technical Developer Community and Technical Oversight Board https://www.openapis.org/participate/how-to-contribute/governance Q.Does the formal specification have a defined policy for version management?
Yes The latest version of the specification can be found on GitHub. https://github.com/OAI/OpenAPI-Specification/tree/master/versions The difference between versions and migration documentation are published on GitHub.
Q. Is this an existing European standard or an identified technical specification in Europe? (Note: CEN, CENELEC and ETSI are the European standards bodies. Technical specifications provided by organisations other than CEN, CENELEC or ETSI can be under consideration to become a European standard or an identified technical specification in Europe for example through the Multi Stakeholder Platform.)
No.
Q. Does this specification or standard cover an area different from those already identified or currently under consideration as an identified European standard or specification?
Yes As far as our research shows
jontybale
commented
7 years ago Just to jump in here and provide some additional thoughts - I am currently working on some proof of concepts internally at the DWP for documenting APIs using OAS, including the development of an API Hub - very early days however but we do see the adoption of a documentation standard such as this very useful.
I personally have found OpenAPI/Swagger to be vital when designing APIs and discussing proposed implementations with colleagues - prior to using OAS I would normally document API endpoints in a Google sheets and circulated it for discussion.
It just gives you a clean, declarative, common language in which to discuss API specifications.
As to when to use OAS - I have found that the best option has been to create an up front spec as a stand alone file when designing a service, then transition to annotations once the work to deliver an endpoint is completed.
davidcarboni
commented
7 years ago I thought I'd add a couple of counterpoints. To be clear, the benefits are pretty compelling and well covered above, so this is about adding to the discussion by acknowledging costs rather than making a case for doing something different. I'm interested to know if these resonates and if there are other costs worth considering:
In an ideal world, developer-friendly (i.e. human readable) 'just good enough' documentation would be generated from your actual production code on Github with minimal effort and structure in the code itself. I'm nodding to Javadoc as the original and Python doc strings, with a sprinkling of annotations along the way.
It's a question for API developers everywhere and not specific to government, but government can support and influence for simple, clear standards.
simon-cutts
commented
7 years ago Writing a spec like OpenAPI with a tool is a good thing, right? A tool abstracts you away from having to retain all the complexities of the spec in your head. In my experience, specs generated from annotations tend to be light on detail. Also, not all tech supports annotation for SoapAPI. For instance, we are using AWS severless tech like API Gateway and Lambdas; API Gateway can work with an existing OpenAPI, but neither Gateway or Lambda's support annotations.
edent
commented
7 years ago Our current plan is to take this through the approval process once v3 has been released.
The release candidate is available, and I would encourage all of you to read and leave feedback.
https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc0/versions/3.0.md
timgent
commented
7 years ago Sorry for coming in late, and I'll admit to not having read all the good detail in this thread. I think the OpenAPI spec is a good candidate, though wanted to mention that for producing rich documentation for APIs I do think there are other options. The one we've used has been Rest-assured with Spring RestDocs (not actually limited to Spring). They are Java libraries though so limited. We have a brief write up of some of this here: https://github.com/UKHomeOffice/api-guide-for-developers#a-name-documentationacceptance-tests-documentation-and-creating-a-mock-of-your-api
I realise this approach has drawbacks too, not least that it is limited in consistency across languages. Also hopefully we'll get tools built on OpenAPI spec at some point that allow richer, more flexible documentation where needed.
edent
commented
7 years ago The specification has been finalised! Press Release
We will now begin consulting on whether to mandate this as the way to document APIs.
Full specification https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
psd
commented
7 years ago My biggest concern is that the challenge is to around improving documenting a class of APIs, but by From a quick attempt to use it to describe the register API, it seems whilst OpenAPI works well for RPC interfaces, it can't describe hypermedia interfaces which span multiple domains. I worry about other common HTTP patterns which can't be described and which would be precluded if this specification was mandated as an open standard.
pwin
commented
7 years ago I agree with the caution from @psd about any mandate precluding descriptions. This could leave holes in documentation.
Also, I've not noticed in the openAPI scope for wrapping XML Schema components for defining request or response (it seems to do JSON) whereas RAML 1.0 does.
edent
commented
7 years ago Thanks @psd - do you have any specific examples of common HTTP patterns which you think will be a problem?
I agree that, based on this issue at OAI, that HATEOS might be problematic. Would it be enough to say that this is the standard for REST APIs?
It appears that v3 supports multiple servers - is that what you mean by multiple domains?
puntofisso
commented
7 years ago I must concur with the comments so far. I have used Swagger since version 2 to document the API behind data.sgul.ac.uk and on several freelance projects and it's good - assuming your API is fully REST.
The framework is powerful and a great tool for your developers/users, especially as it allows the generation of "live" API docs (where the devs can try it out), and it's easy to translate into other formats (e.g. via XSLT etc). However, I remember looking into documenting SOAP services and I could not find much in this direction.
You might as well argue that a SOAP service requires an entirely different approach. Therefore, I would recommend OpenAPI/Swagger if you were to suggest its adoption as a standard to document REST API alone.
Notwithstanding our comments, you might want to have a chat with the guys behind the US data.gov, as they developed and released an API Management System called API-Umbrella. They were trying to build Swagger capabilities into it (https://github.com/NREL/api-umbrella/issues/211). Last time I spoke with them, they seemed quite keen on talking to compare strategies with people this side of the pond.
kolektiv
commented
7 years ago I think it's a reasonable approach for documenting certain types of APIs. HATEOAS is likely to be problematic, and the further from simple resource-centric APIs you get, the more likely it is to be difficult. It would be good to caveat the mandate with what kinds of APIs it should apply to. It would be a shame to stifle innovation (or the adoption of things like GraphQL where they are appropriate - subjective discussion aside).
I think it would make sense as a strong recommendation for a certain class of problem but "all APIs" would be destructive.
crystalmark
commented
7 years ago HMRC chose RAML because, at the time, RAML annotations swayed the decision. It was a very close race between Swagger and RAML. Now we all wish we went with Swagger because the tool set is better and better supported. We can’t upgrade to RAML 1.0 because the toolset is not mature or complete enough compared to RAML 0.8.
edent
commented
7 years ago As an update on https://github.com/alphagov/open-standards/issues/31#issuecomment-268477102
This is purely a documentation standard for APIs which can suitably be described in this standard.
pwin
commented
7 years ago Documentation alone isn't anything like as good as documentation with tools to test. If it's documentation alone then you might as well just have a text file or a word document. We need to have some structured data that we can programme against for automation-----Original Message-----From: notifications@github.comSent: Wed, 02 Aug 2017 10:23:37 +0000 (UTC)To: open-standards@noreply.github.comSubject: Re: [alphagov/open-standards] Evaluate OpenAPI Specification as a common API description format (#31)As an update on my previous comment #31 (comment) This is purely a documentation standard for APIs which can suitably be described in this standard.
This challenge is around clear and consistent documentation of existing and new APIs. It is only to be used where suitable. That is, it is specifically for REST-like APIs which can be described in v3. If we select this, GDS should aim to become a member of the OAI organisation. We can then help to develop the standard to meet our users' diverse needs.
—You are receiving this because you commented.Reply to this email directly, view it on GitHub, or mute the thread.
matthew-shaw
commented
7 years ago I'm using OAPI v2 (Swagger) at HMLR. Looking forward to using v3 release with better JSONSchema as some relationships aren't supported in v2.
I'm also using the API definition JSON (swagger) to unit and integration test against, since the models define the request/response schemas. I.e. if the interface is changed, the tests fail until the implementation matches. I'm defining these as the Technical Architect on a service, so I'm responsible for the interfaces between components.
Same goes for doing JSON Schema validation, since definitions are read in to the app at runtime and used to validate requests. This avoids some duplication and makes them easier to change later.
Happy to share example implementations if needed. Generally, I'm all in favour of the OAPI standard, but we haven't been able to fully adopt it until now because of the JSON Schema limitations. With that resolved, I'd want to push this forwards.
davidread
commented
7 years ago Do people care if an API service uses OpenAPI under the hood? I don't see many examples of automatic clients struggling trying to read human-readable docs.
So I'm not convinced this should be a standard that gov mandates, in the same way that gov doesn't require developers to select particular internal tech, like Postgres or Nginx. What is the user need for the user to access the OAPI definition?
I'm more in favour of adding to the Service Manual - a larger section on APIs highlighting the best practices we are talking about (e.g. showing example requests & responses, in-browser sandbox, self-service API keys), based on the discovery work, and that suggest the OAPI ecosystem is a short-cut to implementing some aspects of that.
MikeRalphson
commented
7 years ago What is the user need for the user to access the OAPI definition?
Client-side code/SDK generation is one such driver. It is far easier to create and maintain such code if a public machine-readable API definition exists (though this doesn't mean it has to be OpenAPI, nor that it has to be mandated). Developers could also mock a server to test with locally etc.
davidread
commented
7 years ago @MikeRalphson That is a fair point. I'm surprised that it has not been mentioned in any of the reasoning in the proposal, this discussion, nor was it picked up in the Discovery research. I guess it is more useful for typed languages like C++ & Java, and where the user integrates the API service more deeply - perhaps the research was looking at more usual casual use of APIs?
I'd agree that we need to stop devs writing API docs manually - they should structure them, and for that OpenAPI is the best open choice. It just seems a bit strange that we're using the open standards board to push this change that is more about usability and design change - the open thing is a secondary benefit/concern.
govuklaurence
commented
7 years ago I'm in general support of OpenAPI - but it should be noted that the specification is not being updated perhaps as quickly as it should be (for example, JWT auth, which is quite widely used now, is not supported in the standard).
The documentation generation is a feature I've used extensively and that I'm VERY happy with. There's some provision for linked data/HATEOAS, but this shouldn't be a driver for adoption. IMO input/output schemata are the most valuable tool.
MikeRalphson
commented
7 years ago for example, JWT auth, which is quite widely used now, is not supported in the standard
@govuklaurence See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#jwt-bearer-sample
PeterParslow
commented
6 years ago (from Michael Gordon of OS:) I would endorse the main points in this thread:
• OpenAPI is a good standard for machine readable documentation and has good tooling support to generate other docs, tests etc. of it. It seems to be generally winning in terms of adoption • Use of any particular documentation standard should absolutely not constrain API design itself and should only be used where appropriate.
I would add that:
• OpenAPI specs are not a replacement for human readable documentation and help. They should complement this. In an ideal world they form the basis that other documentaiton is built off of (whether that’s automated or manual).
We’re using OpenAPI in the Cityverve public API workgroup, and I believe there are moves afoot to utilise it in some OGC stuff (potentially some testbed things).
SteveMarshall
commented
6 years ago (Cross-posting from the community mailing list, at @edent's request)
We’re using OpenAPI in a few places in MOJ. I’m still yet to be convinced it’s good enough to be government’s (or even MOJ’s) chosen standard for documenting all our APIs, though. The API documentation space is very actively in flux right now (with OpenAPI, JSON API, and others actively being developed), so it might be a bit premature to pick a single standard.
A few things about OpenAPI concern me, based on what I’ve seen so far:
info.version is required, and is the version of the OpenAPI document (not the version of OpenAPI being used, or the version of the API itself), but Swagger’s docs say that info.version is the version of the API itself. The schema for OpenAPI v2 goes further, to say that info.version is “A semantic version number of the API.” Given that every version bump to web APIs is a breaking change for all consumers, I’m particularly uncomfortable endorsing that as a way to version web APIs (and am generally uncomfortable with web APIs being versioned).All of those, to one degree or other, seem to be detrimental to making properly RESTful APIs so, as Paul suggests, I’d say we offer OpenAPI as one option for documenting APIs, but maybe have some pointers for when it may be problematic?
audreyt
commented
6 years ago (Cross-posting from PDIS.tw forum, at @edent's request)
Taiwan's National Development Council have implemented these measures:
Translated the OAS3 specification from Linux Foundation into a National Development Council standard document.
Published the national open data platform's own machine-to-machine RESTful interface as apis.json index.
Following automated validation of accessibility A+ standards, we encourage agencies to use automated acceptance-test OAS toolkits to validate APIs.
The National Development Council periodically convenes joint IT leadership meetings on national and local levels. We held an "OAS Town Hall" and published the full transcript online.
Before ratification, we also sought advice with local experts, as well with Rufus Pollock from the Open Knowledge foundation (initial meeting, follow-up meeting).
We have included two key Linux Foundation standards, the OAS3 specification as well as open source license manifest (including but not limited to SPDX) into the procurement template for digital services.
We are also amending "Regulations for Selection and Fee Calculation of Technical Services Providers Entrusted by Entities " to legally authorize all IT departments to ask vendors for conformance to OAS at little or zero additional cost.
garethr
commented
6 years ago This is purely a documentation standard for APIs
I would be very wary of treating OpenAPI purely as something used to document an API. Doing so brings a lot of complexity but misses out on most of the features in my experience of using and consuming it. Reading some of the original comments it feels like a mismatch exists between folks wanting something like a standard HTML document describing an API for end users, and what OpenAPI is, both of which could be described as "documentation". The reality is OpenAPI is documentation (in a very general sense), which can used to generate HTML (or similar) documentation for end users. For instance the user research purely focuses on the end user docs and ignores other broader meanings of documentation. As a concrete example I'd say things like http://petstore.swagger.io/ are examples of clients using OpenAPI, not OpenAPI itself.)
OpenAPI also only covers a particular type of HTTP based API. What happens if my API can't be described using OpenAPI (it's using GRPC, graphql, different HTTP semantics, etc.). Where does the burden of proof lie when it comes to arguing that this isn't possible in a particular case? Is that understandable to potential API consumers or does the standard exert pressure to do the wrong thing?
It's also worth noting that although the v3 spec has been published, that version isn't in use anywhere to my knowledge yet. And the tooling around the standard which exists for v2 and before doesn't yet exist. Neither of those means it's not the right option, but I would question the answer to the question:
Has the formal specification been used for different implementations by different vendors/suppliers?
Taking the formal specification to be OpenAPI v3 the answer is really No.
I think it's worth very clearly defining the scope for this standard as it has the potential to be widely misused otherwise I fear. It might also be the case the scope ends up so tight that a Government-wide standard doesn't make sense. I think it's also worth waiting on usage and tooling around v3. I have no-doubt that will come, but until it does mandating a standard will see a lot of cycles wasted on building the tools to produce and consume it.
AlecMulinder
commented
6 years ago (From SteveMarshall) ...All of those, to one degree or other, seem to be detrimental to making properly RESTful APIs so, as Paul suggests, I’d say we offer OpenAPI as one option for documenting APIs, but maybe have some pointers for when it may be problematic?
I think pointing out where the standard is problematic is a very good suggestion. I also like an earlier suggestion of at least referencing it as a best practice approach in the Service Manual.
I'd favour a stronger endorsement and also like the approach i think initially suggested by @edent of adopting a standard and then influencing its further development. I like very much the comments by @audreyt as they illustrated how standards adoption can be influenced and shaped.
Has there been any benefits analysis undertaken in comparison to RAML?
BillSwirrl
commented
6 years ago We've had generally good experiences with OpenAPI, but I'd agree with several other commenters that proposing it as a best practice rather than as a standard is probably more appropriate at this stage.
It's a good way to go for some styles of API, but we could get in a mess trying to define what subset of all APIs are the ones for which OpenAPI should be mandatory.
Pointing to it in the Service Manual, and explaining what aspects of OpenAPI are desirable and why, sounds like a very positive step - and would avoid the risks of accidentally pressuring developers to do the wrong thing in some circumstances.
edent
commented
6 years ago I met with some Civil Servants from New Zealand - they're using Swagger / OpenAPI for their Government APIs.
Sample links:
edent
commented
6 years ago We had a meeting with Ole Lensma the CTO of SmartBear. Good discussion around some of the topics mentioned here. Will see if we can publish a summary before making our recommendation.
edent
commented
6 years ago Swagger is being used by the U.S. General Services Administration.
They are looking to update to OpenAPI - see https://github.com/GSA/code-gov-api/issues/126
Lawrence-G
commented
6 years ago See the Inside GOV.UK blog post - What we learnt from creating API documentation
The GOV.UK team talk about their use of OpenApi version 3 and their intention to feedback into this challenge.
edent
commented
5 years ago Just had this from the EU's MSP.
Please note the CAMSS Team has finalised the review of the submission form of the Open API Specification v3.0 technical specification submitted by the Netherlands for identification in accordance with Article 13 & 14 of Regulation (EU) No 1025/2012. https://webgate.ec.europa.eu/fpfis/wikis/display/ICTspecsIdentification/OAS+Submission+form?preview=/293411144/293411151/OAS%20v3.0%20Submission%20form_v1.0.DOC In accordance with step 1 of the MSP streamlined evaluation process (documentICT/MSP(2018) 014a rev 1) the CAMSS Team will proceed now with the elaboration of a draft evaluation report.
PeterParslow
commented
5 years ago Hi Terence, I have a log on to the EC WebGate, but that link returns Page Not Found. This may be some permission issue (I may not have permission to view that bit) - but could you check the URL you've posted?
edent
commented
5 years ago @PeterParslow URL is right - but the content has disappeared. I'll try to find out where it has gone.
edent
commented
5 years ago That link should now work. I've attached the Open API v3 evaluation here as well. 625 OAS v3.0 Submission form_v1.0.DOC.zip
edent
commented
5 years ago the CAMSS Team has finalised the draft report of the OAS OpenAPI Specification v3.0 technical specification submitted by the Netherlands for identification in accordance with Article 13 & 14 of Regulation (EU) No 1025/2012.
The draft evaluation report has the number ICT/MSP(2018)627: https://circabc.europa.eu/sd/a/d357dbdc-3ad1-46f9-9f79-53d280d06a6c/627%20OAS_3-0%20(OAI)%20CAMSS%20DRAFT%20REPORT.odt CAMSS team believed that OAS developed by the Open API Initiative (OAI) complies with the requirements for the identification of ICT technical specifications set out by Annex II of Regulation (EU) No. 1025/2012. In accordance with step 2 of the streamlined evaluation process, MSP members are invited to provide their feedback within three weeks (1st October 2018). One week after the end of the three-week period for feedback, the CAMSS Team will produce the final version of this report that will be sent for advice. You can find the planning and any further document concerning this process in wiki.
https://webgate.ec.europa.eu/fpfis/wikis/display/ICTspecsIdentification/OAS+Planning
chris-little
commented
5 years ago The Met Office is using OpenAPI V3 to define and implement data access services: "DataPoint" and "Weather on the Web". The latter is a global international initiative with US, Europe, etc involvement. International work done via OGC, for later endorsement, we hope, by UN's WMO. OGC has specified a new version, 3.0, of its Web Feature Service standard, currently out for public comment. Weather on the Web built on this. Further OGC sponsored hackathons/plugfests/codesprints being planned for later in the year for updating other OGC standards such as WMS, WMTS, WCS. Probably one in US and one in Europe. OpenAPI is a given.
I'll update later with some links.
rb-hmrc
commented
5 years ago So the latest position from us in HMRC is that we still have moving to support OpenAPI as an aspiration for the API Platform. It's definitely our direction of travel. We have some large pieces of upgrade work starting at the moment that will make our Platform more future proof, but after that we will want to revisit OpenAPI support and examine if it's the right time to add that enhancement. Hopefully the concerns raised by other dept's above in this thread may have been addressed by that point.
The main thing holding us back from doing it now is that we've already invested a lot in making RAML work, so we have many strong user needs higher up our priority list.
Evaluate OpenAPI as a standard for describing APIs
Can OpenAPI be the standard used to describe APIs?
Category
Challenge Owner
I'm Ben Henley, a tech writer for GaaP
Short Description
OpenAPI/Swagger is a standard way to describe APIs. It provides a machine-readable description of an API which can be generated by the developers who work on the API. Swagger can be used to generate parts of the documentation, and to create tools like interactive API explorers. There are many tools available which understand Swagger. This makes it easier to maintain accurate documentation and update it quickly. At least two GDS projects already have Swagger descriptions of their APIs.
User Need
Developers who use government APIs need accurate documentation. If all projects that produce APIs were required to maintain a Swagger description, it would make it easier to introduce common documentation tools and make documentation more accurate.
Expected Benefits
Developers would benefit from more accurate API documentation and improved ways to learn about the APIs, like interactive tools. API documentation would be standardised and consistent between projects, reducing time spent for developers to find the information they need. This will increase trust in documentation and reduce time spent on support and increase the pace of integration. Tech writers will need to spend less time maintaining documentation. A Swagger description may also be required for other API-related tools, like monitoring services, management tools and API gateways.
Functional Needs
Teams must be able to produce and maintain Swagger descriptions of their APIs.