Evaluate OpenAPI Specification as a common API description format #31
Comments
|
Thanks @benh-gds - this looks like a great candidate for us. We'll start to look into this now. |
|
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. |
|
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 ***@***.***> 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
<#31 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ASwmPm9ENcaa_N8UYB8eauFaTDp7UfECks5rJ6CGgaJpZM4LOXkU>
.
|
edent
changed the title
|
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 |
|
To address some concerns that people have raised with me offline.
|
|
We have some research from @RosalieDM around this. Will share in public once suitably redacted. |
|
Some previous thoughts from last year https://governmentasaplatform.blog.gov.uk/2016/01/14/improving-developer-documentation/ |
|
Presentation given to MoJ about the research we've done on the need for good documentation. |
|
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. Developer API documentation user needsThese 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). 1) I need a quick way to start using the API
2) I need to experiment with the API before I sign up
3) I need to be able to quickly search the documentation
4) I need to quickly understand how the product works
5) I need a way to assess a product/ I need to know how to classify product, eg whether its something I build or buy
6) I need to know whether the API is right for my service
7) I need to know I can trust the API / I need to know the API is reliable and secure
8) I need to know the API documentation is up to date/ I need to know if changes happen to the technologies I’m using/ I need to make sure I don’t let the product become out of date/ I need to know which version of the product I’m using.
9) I need to know whether I can recommend the API
10) I need to know how to make difficult updates to the product I’m using
11) I need to know there’s support available when I use the info/ I need to feel involved in the API community/ I need to report problems with the API.
12) I need to understand when I’ve made a mistake connecting to the API
13) I need to be able to abide by the government’s data sharing agreements
API doc tool needed features
|
Lawrence-G
changed the title
|
Looping @timblair into the conversation as this will affect APIs that he manages. |
|
Looks like a preview release of v3 of the OAI spec is due at the end of February. |
|
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 |
|
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 ) ApplicabilityQ. Does the formal specification address and facilitate interoperability between public administrations? Yes Q. Does the formal specification address and facilitate the development of information or IT systems in government? Yes Q. Are the functional and non-functional requirements for the use and implementation of the formal specification appropriately detailed? Yes Q. Is the formal specification applicable and extensible for implementations in different domains? Yes Q. Is the formal specification largely independent from products of single providers (either open source or proprietary)? Yes 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 MaturityQ. Has the formal specification been sufficiently developed and in existence for a period to overcome most of its initial problems? Yes 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 Q. Has the formal specification sufficient detail, consistency and completeness for the use and development of products? Yes Q. Does the formal specification provide available implementation guidelines and documentation for the implementation of products? Yes Q. Does the formal specification provide a reference (or open source) implementation? Yes Q. Does the formal specification address backwards compatibility with previous versions? Q. Have the underlying technologies for implementing the formal specification been proven, stable and clearly defined? Yes OpennessQ. 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 Q. Is information on the standardisation process publicly available? Q. Information on the decision making process for approving formal specifications is publicly available? Yes Q. Are the formal specifications approved in a decision making process which aims at reaching consensus? Yes Q. Are the formal specifications reviewed using a formal review process with all relevant external stakeholders (e.g. public consultation)? Yes Q. All relevant stakeholders can formally appeal or raise objections to the development and approval of formal specifications? Yes Q. Relevant documentation of the development and approval process of formal specifications is publicly available (e.g. preliminary results, committee meeting notes)? Yes Q. Is the documentation of the formal specification publicly available for implementation and use at zero or low cost? Yes Intellectual property rightsQ. Is the documentation of the IPR for formal specifications publicly available (is there a clear and complete set of licence terms)? Yes Q. Is the formal specification licensed on a royalty-free basis? Market supportQ. Has the formal specification been used for different implementations by different vendors/suppliers? Yes Q. Has the formal specification been used in different industries, business sectors or functions? Yes Q. Has interoperability been demonstrated across different implementations by different vendors/suppliers? Yes Q. Do the products that implement the formal specification have a significant market share of adoption? Yes Q. Do the products that implement the formal specification target a broad spectrum of end-uses? Yes Q. Has the formal specification a strong support from different interest groups? Yes - PotentialQ. Is there evidence that the adoption of the formal specification supports improving efficiency and effectiveness of organisational process? Yes Q. Is there evidence that the adoption of the formal specification makes it easier to migrate between different solutions from different providers? Yes 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 Q. Is there evidence that the adoption of the formal specification positively impacts security? Yes Q. Is there evidence that the adoption of the formal specification can be implemented alongside enterprise security technologies? Yes Q. Is there evidence that the adoption of the formal specification positively impacts privacy? No Q. Is the formal specification largely compatible with related (not alternative) formal specifications in the same area of application? Yes 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 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 Q. Does the formal specification have a defined maintenance and support process? Yes Yes CoherenceQ. 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 |
|
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. |
|
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. |
|
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. |
|
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 |
|
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: 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. |
|
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 |
|
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. |
|
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. |
|
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? |
|
I must concur with the comments so far. 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 (NREL/api-umbrella#211). Last time I spoke with them, they seemed quite keen on talking to compare strategies with people this side of the pond. |
|
(from Michael Gordon of OS:) • 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 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). |
|
(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:
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? |
|
(Cross-posting from PDIS.tw forum, at @edent's request) Guiding PolicyTaiwan's National Development Council have implemented these measures:
Validation mechanismFollowing automated validation of accessibility A+ standards, we encourage agencies to use automated acceptance-test OAS toolkits to validate APIs. Promotion mechanismThe 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). Procurement supportWe 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. |
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:
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. |
|
(From SteveMarshall) 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? |
|
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. |
|
I met with some Civil Servants from New Zealand - they're using Swagger / OpenAPI for their Government APIs. Sample links:
|
|
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. |
|
Swagger is being used by the U.S. General Services Administration. They are looking to update to OpenAPI - see GSA/code-gov-api#126 |
|
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. |
|
Just had this from the EU's MSP.
|
|
Hi Terence, |
|
@PeterParslow URL is right - but the content has disappeared. I'll try to find out where it has gone. |
|
That link should now work. I've attached the Open API v3 evaluation here as well. |
|
|
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. I'll update later with some links. |
|
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. |
|
My view from Network Rail is that we have not used OpenAPI yet, but we have made use of swagger for internal APIs. |
|
All I'm a technical writer within GDS, and am the new challenge owner. Thank you for your feedback, both historical and recent, on this challenge. I have drafted a proposal to take to the Open Standards Board either in June or later in the year. This proposal is attached below. Please be advised that this is a first draft, and I would like to invite any and all feedback on this content. This feedback can cover the overall approach, the subject matter covered, whether anything is missing, or anything else. Please provide your comments by 8 May 2019. If you have any questions, please tag me in your comment and I'll respond to you directly. Kind regards Jon Glassman |
Draft Proposal for feedback: Recommend OpenAPI3 to describe REST APIsIntroductionThis proposal is to recommend that government departments use the OpenAPI3 specification to describe their REST APIs. Using OpenAPI3 for REST APIs means that departments would be consistent in the way they describe their APIs. It would make it easier when introducing common tools across government to read, display and update the API reference documentation. The proposal is not a mandate as OpenAPI 3 may not be the most suitable API specification to use. User need approachThe user need identified by this proposal is to maximise consistency in and accuracy of API reference documentation across government. Adopting the OpenAPI 3 specification should help to achieve this. Users in the context of this proposal include government departments who create and maintain APIs, and need accurate API reference documentation. Individual users include but are not limited to developers, service managers, product owners and technical architects. Achieving the expected benefitsIf departments use the OpenAPI3 standard, they would be consistent in the way they describe their APIs. Departments would be able to use OpenAPI3 to auto-generate accurate and up to date API reference documentation irrespective of language. The specification will also enable departments to validate, version, maintain and update this generated documentation. This could help increase adoption of these APIs across government by reducing time spent by departments gaining familiarity with different architectures. It would free up developer and non-technical resource as they would spend less time trying to understand the API. Departments will also benefit from being able to send test requests to their API endpoints using different methods in the interactive API explorer, as well as use other available tooling. When OpenAPI 3 may not be suitableThe OpenAPI 3 framework is a powerful tool for working with and describing REST APIs. However, departments must assess if OpenAPI3 is the correct framework to document their APIs. Firstly, OpenAPI 3 is for REST APIs only, and cannot describe SOAP APIs or APIs that use GRPC or GraphQL. Additionally, OpenAPI 3 covers the majority but not all possible styles of REST APIs. Currently, OpenAPI 3 has a description of itself located at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema. The OpenAPI 3 machine-readable and verifiable JSON schema is still being finalised. This makes it more difficult to assess and verify if an API complies with the OpenAPI 3 specification. This could potentially lengthen the development time of an API written in OpenAPI 3 as it would be harder to spot and fix bugs and issues during development. However, other validation tools exist. These assess APIs on non-schema criteria such as the API data and references. Some of these tools are located at https://openapi.tools/. Additionally, it must be noted that a JSON Schema validation does not guarantee compliance, because a JSON schema does not allow for validation of all use cases in the specification. Departments should also assess what tooling is available for their chosen API specification. There are currently multiple OpenAPI 3 tools that enable users to, for example, validate their API (as mentioned above), integrate their API into web pages, or translate an OpenAPI 3 specification into another specification such as RAML. This tooling is regularly expanding, but is not fully comprehensive yet. Other API specifications also have tooling, for example RAML has multiple testing tools located at https://raml.org/developers/test-your-api. Departments should assess what tooling is most appropriate for their use case. Other steps to achieving interoperabilityThis proposal is only concerned with promoting consistent and accurate API reference information across government. This is because the OpenAPI specification only covers reference information such as the API’s endpoints. Fully developed API documentation includes other information such as quick start guides, API keys, running a sample application, rate limits and many other subjects. Government departments should still write the non-reference parts of API documentation. This challenge does not include how government departments write their APIs (for example syntax, response format) or where those APIs live. |
|
@jonathanglassman I welcome this proposal, because the international meteorological community has started to move in this direction with its Weather on the Web API, building on the work for geospatial APIs in OGC and W3C with past and forthcoming hackathons. I am a little concerned about the use of the term 'REST'. Apart from igniting theological architecture flame wars, we find that the key issue is the 'search pattern' as perceived by the end user rather than whether the API is truly RESTful or not. |
Proposal for submission to the Open Standards Board: Recommend OpenAPI3 to describe RESTful APIsIntroductionThis proposal is to recommend that government departments use the OpenAPI 3 specification to describe their RESTful APIs. Using OpenAPI 3 for RESTful APIs means that departments would be consistent in the way they describe their APIs. It would make it easier when introducing common tools across government to read, display and update the API reference documentation. The proposal is not a mandate as OpenAPI 3 may not be the most suitable API specification for all use cases. User need approachThe user need identified by this proposal is to maximise consistency in and accuracy of API reference documentation across government. Adopting the OpenAPI 3 specification should help to achieve this. Users in the context of this proposal are government departments who create and maintain APIs, and need accurate API reference documentation. Individual users include but are not limited to developers, service managers, product owners and technical architects. Achieving the expected benefitsIf departments use the OpenAPI 3 standard, they would be consistent in the way they describe their APIs. Departments would be able to use OpenAPI 3 to automatically generate accurate and up to date API reference documentation irrespective of language. The specification will also enable departments to validate, version, maintain and update this generated documentation. This could help increase adoption of these APIs across government by reducing time spent by departments in understanding different APIs. Departments will also benefit from the OpenAPI 3 tooling. For example, they will be able to send test requests to their API endpoints using different methods in the interactive API explorer. When OpenAPI 3 may not be suitableThe OpenAPI 3 framework is a powerful tool for working with and describing RESTful APIs. However, departments must assess if OpenAPI 3 is the correct framework to document their APIs. Firstly, OpenAPI 3 is for RESTful APIs only, and cannot describe SOAP APIs or APIs that use GRPC or GraphQL. Additionally, OpenAPI 3 covers the majority but not all possible styles of RESTful APIs. Currently, OpenAPI 3 has a description of itself located at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema. The OpenAPI 3 machine-readable and verifiable JSON schema is still being finalised. This makes it harder to assess and verify if an API complies with the OpenAPI 3 specification. This could potentially lengthen the development time of an API written in OpenAPI 3 as it would be harder to spot and fix bugs and issues during development. However, other validation tools exist. These assess APIs on non-schema criteria such as the API data and references. Some of these tools are located at https://openapi.tools/. Additionally, it must be noted that a JSON Schema validation does not guarantee compliance, because a JSON schema does not allow for validation of all use cases in the specification. Departments should also assess what tooling is available for their chosen API specification. There are currently multiple OpenAPI 3 tools that enable users to, for example, validate their API (as mentioned above), integrate their API into web pages, or translate an OpenAPI 3 specification into another specification such as RAML. This tooling is regularly expanding, but is not fully comprehensive yet. Other API specifications also have tooling, for example RAML has multiple testing tools located at https://raml.org/developers/test-your-api. Departments should assess what tooling is most appropriate for their use case. Other steps to achieving interoperabilityThis proposal is only concerned with promoting consistent and accurate API reference information across government. This is because the OpenAPI specification only covers reference information such as the API’s endpoints. Fully developed API documentation includes other information such as quick start guides, API keys, running a sample application, rate limits and many other subjects. Government departments should still write the non-reference parts of API documentation. This challenge does not include how government departments write their APIs (for example syntax, response format) or where those APIs live. |
|
For interest - and in support! - OS has agreed internally that our APIs should all have OpenAPI specifications, and we support adopting the current version. Of course, that doesn't yet mean that we've created OpenAPI specs for all our APIs, but we're working on it! |
|
New to the group - would like to support the current process and welcome the proposal. From where I am standing , the heritage/cultural sector is big on accelerating enablers for media exchange across systems - both internal and external. Particularly encouraged by the multipart file uploader which potentially facilitates the large media files. |
|
The OpenAPI profile has been published on GOV.UK |
and others
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.
The text was updated successfully, but these errors were encountered: