{"id":2726,"date":"2017-08-01T03:30:52","date_gmt":"2017-08-01T03:30:52","guid":{"rendered":"https:\/\/readmeprd.wpenginepowered.com\/?p=730"},"modified":"2024-11-02T17:55:49","modified_gmt":"2024-11-02T22:55:49","slug":"documenting-your-api-in-your-code-with-swagger","status":"publish","type":"post","link":"https:\/\/readme.com\/resources\/documenting-your-api-in-your-code-with-swagger","title":{"rendered":"Documenting Your API Right in Your Code With OpenAPI"},"content":{"rendered":"\n

OpenAPI Specification (OAS), formerly known as Swagger, has become the de facto standard for documenting APIs. While building out our support for it<\/a>, however, we found it was a bit tough to create, manage, and host OAS files.<\/p>\n\n\n\n

There are a few tools for this out there, like Apiary or Swagger Hub. However, these are more focused on designing APIs, rather than documenting them. For people who want to use OAS primarily for documenting existing APIs, it makes much more sense to maintain the documentation inline, right near the code. We’ve built a few OAS-related tools to help!<\/p>\n\n\n\n

Tl;dr:<\/strong> It’s easy to document your APIs right from the code! Install npm install oas -g<\/code>, and run oas init<\/code>. This will guide you through everything! Keep reading if you want more details.<\/p>\n\n\n\n

Need documentation for your API? You can use your oas<\/code>-generated URL in ReadMe for instant documentation! Learn more here.<\/a><\/em><\/p>\n\n\n\n

The Workflow<\/h2>\n\n\n\n
    \n
  1. Create an OAS file:<\/a><\/strong> Use oas<\/code>, a command line tool for creating, managing and uploading OAS files.<\/li>\n\n\n\n
  2. Documenting endpoints:<\/a><\/strong> Use Swagger Inline to extract your OAS defintions right from code comments.<\/li>\n\n\n\n
  3. Hosting your OAS file:<\/a><\/strong> Running oas host<\/code> will upload your file to https:\/\/openap.is<\/a>, a repository for easily sharing Swagger files.<\/li>\n<\/ol>\n\n\n\n

    1. Creating an OAS File<\/h2>\n\n\n\n