Integrating Python Swagger with Continuous Integration

The Continuous Integration (CI) has become a standard practice. It enables teams to build, test, and deploy code changes rapidly and reliably. The Swagger on the other hand is a powerful framework for designing, building, and documenting APIs. Integrating Swagger with the CI pipelines can streamline the API development process and ensure consistency and reliability across the development lifecycle. In this article, we'll explore how to integrate Swagger with Continuous Integration in Python projects.

What is Continuous Integration?

Continuous Integration (CI) is a software development practice where code changes are automatically built, tested, and validated. CI helps detect issues early, ensures that code changes integrate smoothly, and maintains a high quality of code. Popular CI tools include Jenkins, Travis CI, CircleCI, and GitHub Actions.

Benefits of Integrating Swagger with CI

• Up-to-date Documentation: Automatically generate and update API documentation with every code change.
• Automated Testing: Ensure that APIs conform to their specifications through automated tests.
• Consistency: Maintain consistency between the codebase and API documentation.
• Efficiency: Reduce manual effort in maintaining documentation and performing tests.

Setting Up Swagger with CI

Prerequisites

• A project with a RESTful API.
• A CI/CD pipeline configured with tools like Jenkins, Travis CI, CircleCI, or GitHub Actions.
• Swagger/OpenAPI tools installed (Swagger CLI, Swagger Editor, etc.).

Step 1: Define Your API with Swagger

Start by defining your API using the OpenAPI Specification (OAS) in a YAML or JSON file. Here's an example of an OpenAPI definition in YAML:

openapi: 3.0.0
info:
  title: Sample API
  description: API for demonstrating Swagger integration with CI
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

Save this file as swagger.yaml in your project.

Step 2: Set Up Swagger Codegen

Swagger Codegen can generate client libraries, server stubs, and API documentation. Install Swagger Codegen if you haven't already:

npm install -g @openapitools/openapi-generator-cli

To generate documentation, run:

openapi-generator-cli generate -i swagger.yaml -g html -o ./docs

This command generates HTML documentation in the ./docs directory.

Step 3: Integrate Swagger with Your CI Pipeline

Using GitHub Actions

Create a GitHub Actions workflow file in .github/workflows/swagger.yml:

name: CI Swagger Integration

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v2

    - name: Set up Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14'

    - name: Install OpenAPI Generator
      run: npm install -g @openapitools/openapi-generator-cli

    - name: Generate API Docs
      run: openapi-generator-cli generate -i swagger.yaml -g html -o ./docs

    - name: Upload API Docs
      uses: actions/upload-artifact@v2
      with:
        name: api-docs
        path: ./docs

This workflow checks out the code, installs Swagger Codegen, generates the API documentation, and uploads it as an artifact.

Using Jenkins

For Jenkins, create a Jenkinsfile:

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        stage('Install OpenAPI Generator') {
            steps {
                sh 'npm install -g @openapitools/openapi-generator-cli'
            }
        }
        stage('Generate API Docs') {
            steps {
                sh 'openapi-generator-cli generate -i swagger.yaml -g html -o ./docs'
            }
        }
        stage('Archive API Docs') {
            steps {
                archiveArtifacts artifacts: 'docs/**', allowEmptyArchive: true
            }
        }
    }
}

This Jenkins pipeline performs similar steps: it checks out the code, installs Swagger Codegen, generates the documentation, and archives it.

Step 4: Automate API Testing

To automate API testing using Swagger, you can use tools like Postman or Dredd.

Using Postman

Export your Postman collection and write a script to run it using Newman:

newman run postman_collection.json

Add this to your CI pipeline after generating the documentation.

Using Dredd

Install Dredd:

npm install -g dredd

Create a dredd.yml configuration file:

dry-run: null
language: nodejs
hookfiles: null
sandbox: false
server: null
custom:
  apiaryApiKey: null
  apiaryApiName: null
blueprint: swagger.yaml
endpoint: 'http://localhost:3000'

Run Dredd in your CI pipeline:

dredd

Step 5: Monitor and Maintain

Ensure that your CI pipeline runs successfully with every code change. Regularly review and update your Swagger definition to reflect any changes in your API.

Conclusion:

The Integrating Swagger with the Continuous Integration in Python projects can significantly enhance the API development process by the automating documentation generation and validation. By incorporating Swagger into the CI pipeline we ensure that APIs are well-documented, consistent and reliable ultimately improving the overall quality of the software.