It blends "spec" (short for specification) with "tron" (a reference to electronic and futuristic concepts), giving a tech-forward and modern impression.
seamlessly generate comprehensive and dynamically updated API documentation.
Automate API documentation generation through advanced code analysis, ensuring accurate and up-to-date documentation. Utilize intelligent source code examination to produce precise and synchronized API documentation, saving time and guaranteeing accuracy. Enable developers to focus on core tasks while maintaining a well-documented API ecosystem.
Note: This project is still in development and is not ready for production use.
Client
Database
activate virtualenv and install requirements
pip install -r requirements/local.txtVia pip into a virtualenv:
pip install specitronRunning type checks with mypy:
mypy specitronTo run tests, run the following command
To run the tests, check your test coverage, and generate an HTML coverage report:
coverage run -m pytest\
coverage html\
open htmlcov/index.html\ pytest
Clone the project
git clone https://github.com/imperiumx/specitron.gitGo to the project directory
cd specitronInstall dependencies
pip install -r requirements/local.txtStart the server
python mananage.py migrate\
python manage.py runserverfrom openapi_spec_generator import OpenAPISpecGenerator
# Create an instance of the OpenAPI specification generator
generator = OpenAPISpecGenerator()
# Define your API endpoints and their corresponding methods
generator.add_path('/users', 'GET', 'Get a list of users')
generator.add_path('/users/{id}', 'GET', 'Get a user by ID')
generator.add_path('/users', 'POST', 'Create a new user')
generator.add_path('/users/{id}', 'PUT', 'Update a user by ID')
generator.add_path('/users/{id}', 'DELETE', 'Delete a user by ID')
# Generate the OpenAPI specification in JSON format
specification = generator.generate_spec()
# Save the specification to a file
with open('openapi.json', 'w') as f:
f.write(specification)
# Alternatively, you can also print the specification
print(specification)-
- Parsing Source Code: Implement the ability to parse the source code of API projects written in one or more programming languages.
- Endpoint Extraction: Extract API endpoints, HTTP methods, URL paths, query parameters, and request/response headers from the parsed source code.
- Data Model Extraction: Identify data structures, request/response bodies, data types, required fields, and basic validation rules from the source code.
- Documentation Generation: Generate an initial OpenAPI specification document based on the extracted information and provide options for customization.
-
- Advanced Endpoint Analysis: Improve endpoint extraction by handling more complex scenarios like route parameters, nested routes, and route patterns.
- Request/Response Body Analysis: Enhance data model extraction to support nested objects, arrays, and more advanced validation rules.
- Code Annotation Support: Introduce support for code annotations or comments that allow developers to provide additional information for the generator to use in the documentation.
- Customization Options: Expand customization options to allow developers to specify details like response examples, API descriptions, and error handling.
-
- Support for Multiple Programming Languages: Add support for additional programming languages commonly used for API development(Python for now).
- Framework Integration: Integrate with popular web frameworks (e.g., Express.js, Django, Ruby on Rails) to enhance extraction capabilities specific to those frameworks(DRF for now).
-
- Command-Line Interface (CLI): Develop a CLI tool for easy configuration and execution of the OpenAPI generator.
- Graphical User Interface (GUI): Create a user-friendly GUI for configuring and running the generator.
- Build Process Integration: Provide seamless integration with common build tools and CI/CD pipelines for automatic generation of documentation during the development lifecycle.
-
- Authentication and Authorization Support: Extend the generator to extract and document authentication mechanisms (e.g., OAuth, JWT) and authorization requirements.
- Error Handling Documentation: Automatically extract error handling logic from the source code and include it in the generated documentation.
- Versioning Support: Add support for documenting multiple versions of an API and handling version-specific endpoints and data models.
- API Testing Integration: Integrate with API testing frameworks or tools to automatically generate test cases based on the OpenAPI specification.
-
- Stay Up-to-Date with OpenAPI Specification: Regularly update the generator to support the latest version of the OpenAPI specification.
- Monitor Language and Framework Updates: Keep track of updates in programming languages and frameworks to ensure compatibility and make necessary adjustments.
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
See contributing.md for ways to get started.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Before sending patches please make sure you have pre-commit activated in your local git repository:
pre-commit installThis will ensure that your code is cleaned before you commit it.
Please read the Code of Conduct
What is an OpenAPI specification?
An OpenAPI specification is a standardized way to describe and document RESTful APIs. It defines the endpoints, request/response formats, parameters, and other details required to interact with an API.
How does an OpenAPI specification generator work?
OpenAPI specification generators typically analyze source code or API endpoints to extract information about the available endpoints, request/response formats, parameters, and other relevant details. They use this information to automatically generate the OpenAPI specification file, usually in JSON or YAML format.
Can an OpenAPI specification generator support multiple programming languages?
Yes, many OpenAPI specification generators are designed to support multiple programming languages. They can analyze code written in various languages such as Python, JavaScript, Java, Ruby, and more, and generate the corresponding OpenAPI specification.
Can an OpenAPI specification generator be integrated into existing workflows or tools?
Yes, most OpenAPI specification generators offer integrations with popular development tools and workflows. They can be integrated into build systems, continuous integration/continuous deployment (CI/CD) pipelines, documentation platforms, and API management systems to automate the process of generating and updating API specifications.
Distributed under the no License. See LICENSE.txt for more information.
Your Name - @imperiumxx - imperiumx.dev@gmail.com
LinkedIn: https://www.linkedin.com/in/imperiumx/
Project Link: https://github.com/imperiumx/specitron
Use this section to mention useful resources and libraries that you have used in your projects.