what are the best tools for documenting apis?

• spectral

  6 2,245 8.0 TypeScript

  A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI v3.1, v3.0, and v2.0 as well as AsyncAPI v2.x.

  

You can also use linters such as Stoplight's spectral to make sure the API specification is looking good.

• OpenAPI-Specification

  44 28,215 8.6 JavaScript

  The OpenAPI Specification Repository

  

It depends on the type of API. REST APIs are documented with the OpenAPI specification standard. If it's a GraphQL API, you use the Schema Definition Language. gRPC uses Protocol Buffers. Each type of API has its own documentation standard. There's also a specification for event-driven APIs called AsyncAPI!

• SurveyJS

  surveyjs.io sponsored

  Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.

  

• redoc

  35 22,462 7.5 TypeScript

  📘 OpenAPI/Swagger-generated API Reference Documentation

  

That's for the technical documentation. Then there're visualisation tools, and here again you have plenty of choice. For REST, the classic is the Swagger UI, but you can also use fancy visualisations such as Redoc and others.

• dredd

  15 4,125 2.4 JavaScript

  Language-agnostic HTTP API Testing Tool

  

The other thing you want to make sure is that the server is implementing the API correctly. In this space, you can use tools such as Dredd and schemathesis, which look at the API specification and automatically test the server implementation against it.

• Schemathesis

  23 2,091 9.7 Python

  Automate your API Testing: catch crashes, validate specs, and save time

  

The other thing you want to make sure is that the server is implementing the API correctly. In this space, you can use tools such as Dredd and schemathesis, which look at the API specification and automatically test the server implementation against it.

• openapi-generator

  234 19,807 9.9 Java

  OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

  

To add on: If you’re using OpenAPI/Swagger for rest documentation, then their code generator is an option for http/s client generation. IMO the quality of generated code is low and the project is a mess, but it’s not a bad start.

Suggest a related project