https://github.com/AndrewWalsh/at-your-service

Generate OpenAPI 3.1 specifications from network requests in browser environments
https://github.com/AndrewWalsh/at-your-service

api api-documentation codegen generation openapi openapi31 proxy rest

Last synced: about 1 month ago
JSON representation

Generate OpenAPI 3.1 specifications from network requests in browser environments

• Host: GitHub
• URL: https://github.com/AndrewWalsh/at-your-service
• Owner: AndrewWalsh
• License: mit
• Archived: true
• Created: 2022-11-11T02:02:37.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2023-10-18T13:36:57.000Z (11 months ago)
• Last Synced: 2024-07-08T08:57:43.065Z (3 months ago)
• Topics: api, api-documentation, codegen, generation, openapi, openapi31, proxy, rest
• Language: TypeScript
• Homepage: https://atyourservice.awalsh.io/
• Size: 40.6 MB
• Stars: 12
• Watchers: 3
• Forks: 3
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING
  • License: LICENSE

Awesome Lists containing this project

• jimsghstars - AndrewWalsh/at-your-service - Generate OpenAPI 3.1 specifications from network requests in browser environments (TypeScript)

README

        




[![MIT License][license-shield]][license-url]














  

    

  


  


  
at-your-service

  


  


    



        A developer tool for API observability on the browser. Generate OpenAPI specifications and code from network traffic

        


        


        Designed for ease of use. No need to integrate with existing code

      

      


      


      View the Live Demo

      


      


      Report Bug

      ·

      View on npm

      ·

      YouTube Demo

  











  Table of Contents

  


    


      About the Project and Why

    

    


      Features

    

    


      Getting Started

    

    


      How It Works

    

    


      Contributing

    

    


      Limitations

    

    


      License

    

  





## About the Project and Why



This tool is designed to help tackle problems that arise from a lack of awareness on API behaviour.

It records network requests under the hood using a service worker proxy. As the tool makes observations of network traffic over time, it learns the structure of the underlying API.

(back to top)


## Features

- **Spec gen**: autogenerate [OpenAPI 3.1](https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released) specifications from network traffic

- **Code gen**: [convert](https://github.com/quicktype/quicktype) network response bodies into code for 10+ languages including TypeScript, Python, and JSON Schema

- **API Observability**: explore the network layer with enhanced tooling

- **Easy installation**: designed to plug in and go with an existing application

(back to top)


## Getting Started

`at-your-service` features a CLI tool that places its service worker file into a directory. You likely wish to place this in `public` or `static`. See [more information here](https://mswjs.io/docs/getting-started/integrate/browser#where-is-my-public-directory) on common locations for static files.

The service worker must be served from the root of your site. Once this is installed run the start script in your application code.

1. Install the npm package

   ```sh

   npm install -D at-your-service@latest

   ```

2. Add service worker to your `public`, `static`, or otherwise root directory

   ```sh

   npx at-your-service@latest 

   ```

3. Run the start script in your application

   ```ts

   import { startAtYourService } from "at-your-service";

   startAtYourService();

   ```

4. A button to open the drawer will be visible on your site

5. You can view copied OpenAPI 3.1 specifications in [editor-next.swagger.io](https://editor-next.swagger.io/). At the time of writing, you need to manually change the version from `3.1.0` to `3.0.0` after pasting the specification. Support for the new version of the specifcation is an ongoing process

(back to top)


## How It Works

More information on the rationale, functionality, and architecture of the tool [can be found here](https://awalsh.io/posts/developer-tool-api-discovery-observability-frontend/).

(back to top)


## Contributing

A development environment exists in `demo`, which when built is the landing page for the library.

If you have a suggestion that would make this better, please fork the repo and create a pull request.

(back to top)


## Limitations

The library creates specifications that are only as accurate as the underlying observations. If your application relies on a response body that has not been observed, then type information for it will not be available.

Overall the intent is to produce a *best guess* that reveals API behaviour. This will never be a replacement for proper documentation.

(back to top)


## License

Distributed under the MIT License. See `LICENSE` for more information.

(back to top)


[contributors-shield]: https://img.shields.io/github/contributors/AndrewWalsh/at-your-service.svg?style=for-the-badge

[contributors-url]: https://github.com/AndrewWalsh/at-your-service/graphs/contributors

[forks-shield]: https://img.shields.io/github/forks/AndrewWalsh/at-your-service.svg?style=for-the-badge

[forks-url]: https://github.com/AndrewWalsh/at-your-service/network/members

[stars-shield]: https://img.shields.io/github/stars/AndrewWalsh/at-your-service.svg?style=for-the-badge

[stars-url]: https://github.com/AndrewWalsh/at-your-service/stargazers

[issues-shield]: https://img.shields.io/github/issues/AndrewWalsh/at-your-service.svg?style=for-the-badge

[issues-url]: https://github.com/AndrewWalsh/at-your-service/issues

[license-shield]: https://img.shields.io/github/license/AndrewWalsh/at-your-service.svg?style=for-the-badge

[license-url]: https://github.com/AndrewWalsh/at-your-service/blob/master/LICENSE