GitHub Action
Generate Auto Documentation
Update and maintain the documentation for your project with ease.
Given an API file written in a supported language (eg. Python), this action will generate and maintain an OpenAPI spec file (in YAML format) for that file, then open a pull request with the changes and an explanation.
The following Github Secrets must be accessible to the action:
- RUNLLM_API_KEY: The API key for your Runllm account.
- GITHUB_TOKEN: The Github token for the repository.
This action is expected to be used only with push-based workflows. It is recommended to use this action by copy-pasting the following github workflow:
name: Maintain OpenAPI Spec
on:
push:
branches: [main]
paths:
- '<path-to-your-api-file>'
permissions:
contents: write
pull-requests: write
jobs:
update-docs:
runs-on: ubuntu-latest
steps:
- name: Generate OpenAPI Documentation
uses: runllm/generate-docs@v1
with:
runllm_api_key: ${{ secrets.RUNLLM_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}
input_api_file: "<path-to-your-api-file>"
output_spec_file: "<path-to-your-output-spec-file>"
base_branch: "main" # OptionalImagine we have added the following Github Action workflow:
name: Maintain OpenAPI Spec
on:
push:
branches: [main]
paths:
- 'src/books_server.py'
permissions:
contents: write
pull-requests: write
jobs:
update-docs:
runs-on: ubuntu-latest
steps:
- name: Generate OpenAPI Documentation
uses: runllm/generate-docs@v1
with:
runllm_api_key: ${{ secrets.RUNLLM_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}
input_api_file: "src/books_server.py"
output_spec_file: "docs/openapi.yml"Now, let's say we create the following file at src/books_server.py and merge to main:
from flask import Flask, jsonify, request, abort
app = Flask(__name__)
# In-memory database simulation
books = []
@app.route('/books', methods=['GET'])
def get_books():
return jsonify(books)
@app.route('/books', methods=['POST'])
def add_book():
if not request.json or 'title' not in request.json or 'author' not in request.json:
abort(400)
book = {
'id': len(books) + 1,
'title': request.json['title'],
'author': request.json['author'],
'isbn': request.json.get('isbn', ""),
'publishedYear': request.json.get('publishedYear', None)
}
books.append(book)
return jsonify(book), 201
@app.route('/books/<int:book_id>', methods=['GET'])
def get_book(book_id):
book = next((book for book in books if book['id'] == book_id), None)
if book is None:
abort(404)
return jsonify(book)
@app.route('/books/<int:book_id>', methods=['PUT'])
def update_book(book_id):
book = next((book for book in books if book['id'] == book_id), None)
if book is None:
abort(404)
if not request.json:
abort(400)
book['title'] = request.json.get('title', book['title'])
book['author'] = request.json.get('author', book['author'])
book['isbn'] = request.json.get('isbn', book['isbn'])
book['publishedYear'] = request.json.get('publishedYear', book['publishedYear'])
return jsonify(book)
@app.route('/books/<int:book_id>', methods=['DELETE'])
def delete_book(book_id):
global books
books = [book for book in books if book['id'] != book_id]
return jsonify({'result': True})
if __name__ == '__main__':
app.run(debug=True)The action will automatically generate a pull request adding the following OpenAPI spec file at docs/openapi.yml:
openapi: 3.0.0
info:
title: Book Management API
version: 1.0.0
description: This API allows you to manage a collection of books. You can add, retrieve, update, and delete books.
paths:
/books:
get:
summary: Retrieve a list of all books
description: This endpoint returns a list of all books in the collection. Each book is represented with its unique ID, title, author, ISBN, and the year it was published.
responses:
'200':
description: A list of books
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Book'
post:
summary: Add a new book
description: This endpoint allows you to add a new book to the collection. The title and author are required, while the ISBN and published year are optional.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
responses:
'201':
description: The book was successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
'400':
description: The request was invalid. Either the title or author was not provided.
...Future edits to src/book_server.py will continously update the OpenAPI spec file and open corresponding pull requests with any updates.
Never let your documentation get out of date again!