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!
Generate Auto Documentation is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.
Generate Auto Documentation is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.