Convert Figma logo to code with AI

swagger-api logoswagger-core

Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API

7,378
2,178
7,378
810
View on GitHub

Top Related Projects

OAI's avatar

OpenAPI-Specification

28,921

The OpenAPI Specification Repository

OpenAPITools's avatar

openapi-generator

21,595

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

Redocly's avatar

redoc

23,450

📘 OpenAPI/Swagger-generated API Reference Documentation

stoplightio's avatar

prism

4,272

Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations.

apiaryio's avatar

api-blueprint

8,648

API Blueprint

go-swagger's avatar

go-swagger

9,459

Swagger 2.0 implementation for go

Quick Overview

Swagger Core is a Java-based library that helps developers design, build, document, and consume RESTful APIs. It provides tools for generating Swagger/OpenAPI specifications from Java code and annotations, making it easier to create and maintain API documentation.

Pros

  • Simplifies API documentation process by generating Swagger/OpenAPI specs from code
  • Integrates well with popular Java frameworks like Spring and JAX-RS
  • Supports both Swagger 2.0 and OpenAPI 3.0 specifications
  • Offers extensive customization options through annotations and configuration

Cons

  • Learning curve for developers new to Swagger/OpenAPI concepts
  • Can add complexity to projects, especially for smaller APIs
  • May require additional setup and configuration in some environments
  • Documentation generation might not capture all API nuances without manual intervention

Code Examples

  1. Adding Swagger annotations to a REST endpoint:
@Path("/users")
@Api(value = "User Management")
public class UserResource {
    @GET
    @Path("/{id}")
    @ApiOperation(value = "Get user by ID", response = User.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successfully retrieved user"),
        @ApiResponse(code = 404, message = "User not found")
    })
    public Response getUserById(@PathParam("id") Long id) {
        // Implementation
    }
}
  1. Configuring Swagger in a Spring Boot application:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.api"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("My API")
            .description("API documentation using Swagger")
            .version("1.0.0")
            .build();
    }
}
  1. Using Swagger annotations to describe a model:
@ApiModel(description = "User information")
public class User {
    @ApiModelProperty(value = "Unique identifier of the user", example = "1")
    private Long id;

    @ApiModelProperty(value = "Name of the user", example = "John Doe")
    private String name;

    @ApiModelProperty(value = "Email address of the user", example = "john@example.com")
    private String email;

    // Getters and setters
}

Getting Started

To start using Swagger Core in your Java project:

  1. Add the following dependencies to your pom.xml (for Maven):
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.2.8</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-servlet-initializer</artifactId>
    <version>2.2.8</version>
</dependency>
  1. Add Swagger annotations to your API endpoints and models.
  2. Configure Swagger in your application (e.g., using SwaggerConfig for Spring Boot).
  3. Run your application and access the Swagger UI (typically at /swagger-ui.html) to view your API documentation.

Competitor Comparisons

OAI logo

OpenAPI-Specification

28,921

The OpenAPI Specification Repository

Pros of OpenAPI-Specification

  • More comprehensive and widely adopted industry standard
  • Supports a broader range of API description features
  • Actively maintained by a consortium of industry leaders

Cons of OpenAPI-Specification

  • Steeper learning curve for beginners
  • Less direct integration with Java ecosystem

Code Comparison

OpenAPI-Specification (YAML):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Successful response

Swagger-Core (Java):

@Path("/users")
public class UserResource {
    @GET
    @ApiOperation(value = "List users")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successful response")
    })
    public Response getUsers() {
        // Implementation
    }
}

Key Differences

  • OpenAPI-Specification focuses on the API description format
  • Swagger-Core provides tools for Java integration and code-first API development
  • OpenAPI-Specification is language-agnostic, while Swagger-Core is Java-centric

Use Cases

  • Choose OpenAPI-Specification for standardized API documentation across multiple languages
  • Opt for Swagger-Core when working primarily with Java and seeking tight integration with the language ecosystem

Community and Ecosystem

  • OpenAPI-Specification has a larger, more diverse community
  • Swagger-Core benefits from Swagger's established tooling and integrations
OpenAPITools logo

openapi-generator

21,595

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

Pros of openapi-generator

  • Supports a wider range of programming languages and frameworks
  • More frequent updates and active community contributions
  • Offers more customization options for code generation

Cons of openapi-generator

  • Steeper learning curve due to more complex configuration options
  • May generate more boilerplate code in some cases
  • Requires more setup time for initial configuration

Code Comparison

swagger-core (Java):

@Path("/users")
public class UserResource {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Response getUsers() {
        // Implementation
    }
}

openapi-generator (Java):

@RestController
@RequestMapping("/users")
public class UserApiController implements UserApi {
    @Override
    public ResponseEntity<List<User>> getUsers() {
        // Implementation
    }
}

Both swagger-core and openapi-generator are popular tools for working with OpenAPI (formerly known as Swagger) specifications. swagger-core focuses on Java annotations for generating OpenAPI specifications, while openapi-generator is a more versatile tool for generating client SDKs, server stubs, and documentation across multiple programming languages.

swagger-core is generally easier to use for Java developers who want to generate OpenAPI specifications from their existing code. It integrates well with Java frameworks and requires less configuration.

openapi-generator, on the other hand, offers more flexibility and supports a broader range of use cases. It's particularly useful for generating client libraries and server stubs in various languages based on an existing OpenAPI specification.

Redocly logo

redoc

23,450

📘 OpenAPI/Swagger-generated API Reference Documentation

Pros of Redoc

  • Offers a more modern and visually appealing documentation interface
  • Provides better support for customization and theming
  • Generates a single-page application, making navigation smoother

Cons of Redoc

  • Limited to OpenAPI/Swagger specification rendering
  • May require additional setup for complex documentation needs
  • Less extensive ecosystem compared to Swagger Core

Code Comparison

Redoc usage example:

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
  </head>
  <body>
    <redoc spec-url="https://petstore.swagger.io/v2/swagger.json"></redoc>
  </body>
</html>

Swagger Core usage example (Java):

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
          .select()
          .apis(RequestHandlerSelectors.any())
          .paths(PathSelectors.any())
          .build();
    }
}

Redoc focuses on rendering OpenAPI specifications, while Swagger Core provides a more comprehensive toolkit for generating, serving, and consuming OpenAPI-enabled APIs. Redoc excels in creating attractive, user-friendly documentation, whereas Swagger Core offers broader functionality for API development and integration.

stoplightio logo

prism

4,272

Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations.

Pros of Prism

  • Lightweight and fast API mock server and validator
  • Supports multiple API description formats (OpenAPI, Postman Collections)
  • Easy to use CLI and programmatic interface

Cons of Prism

  • Limited to mocking and validation, lacks full API development lifecycle support
  • Smaller community and ecosystem compared to Swagger Core
  • Less extensive documentation and examples

Code Comparison

Prism (JavaScript):

const { createServer } = require('@stoplight/prism-http-server');

const server = createServer({
  spec: './openapi.yaml',
  port: 4010
});

server.listen();

Swagger Core (Java):

OpenAPI oas = new OpenAPIV3Parser().read("openapi.yaml");
SwaggerModule.setOpenAPI(oas);

Swagger swagger = new Swagger(oas);
String swaggerJson = Json.pretty(swagger);

Key Differences

  • Prism focuses on API mocking and validation, while Swagger Core provides a more comprehensive API development toolkit
  • Prism is primarily JavaScript-based, whereas Swagger Core is Java-centric
  • Swagger Core has deeper integration with the broader Swagger ecosystem and tools
  • Prism offers a simpler setup for quick API prototyping and testing

Use Cases

  • Choose Prism for rapid API prototyping, mocking, and validation
  • Opt for Swagger Core when building a full-fledged API development workflow, especially in Java environments
apiaryio logo

api-blueprint

8,648

API Blueprint

Pros of API Blueprint

  • Uses Markdown syntax, making it more human-readable and easier to write
  • Supports more detailed documentation, including examples and descriptions
  • Better suited for design-first API development

Cons of API Blueprint

  • Less widely adopted compared to Swagger/OpenAPI
  • Limited tooling support for code generation and validation
  • Steeper learning curve for developers familiar with JSON/YAML-based formats

Code Comparison

API Blueprint:

# GET /users/{id}
+ Parameters
    + id: 1 (number, required) - User ID
+ Response 200 (application/json)
    + Body
        {
            "id": 1,
            "name": "John Doe"
        }

Swagger Core:

/users/{id}:
  get:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string

Summary

API Blueprint offers a more human-readable format and is better suited for design-first approaches, while Swagger Core benefits from wider adoption and extensive tooling support. The choice between the two depends on project requirements, team preferences, and existing ecosystem integration.

go-swagger logo

go-swagger

9,459

Swagger 2.0 implementation for go

Pros of go-swagger

  • Written in Go, offering better performance and concurrency support
  • Generates server stubs and client SDK in Go, ideal for Go-based projects
  • Supports OpenAPI 2.0 (Swagger) specification out of the box

Cons of go-swagger

  • Limited to Go ecosystem, less versatile than swagger-core
  • Smaller community and fewer resources compared to swagger-core
  • May require more manual configuration for complex scenarios

Code Comparison

swagger-core (Java):

@Path("/users")
@Api(value = "/users", description = "User operations")
public class UserResource {
    @GET
    @ApiOperation(value = "Get all users", response = User.class, responseContainer = "List")
    public Response getUsers() {
        // Implementation
    }
}

go-swagger (Go):

// swagger:route GET /users users listUsers
// Responses:
//   200: usersResponse
func (h *Handler) GetUsers(w http.ResponseWriter, r *http.Request) {
    // Implementation
}

Summary

swagger-core is a more established and versatile tool supporting multiple languages, while go-swagger is tailored specifically for Go projects. go-swagger offers better performance and native Go integration, but has a smaller community and less flexibility across different programming languages. The choice between the two depends on the project's requirements and the development team's preferred language ecosystem.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Swagger Core

NOTE: If you're looking for Swagger Core 1.5.X and OpenAPI 2.0, please refer to 1.5 branch.

NOTE: Since version 2.1.7, Swagger Core also supports the Jakarta namespace. There are a parallel set of artifacts with the -jakarta suffix, providing the same functionality as the unsuffixed (i.e.: javax) artifacts. Please see the Wiki for more details.

NOTE: Since version 2.2.0 Swagger Core supports OpenAPI 3.1; see this page for details

Build Test Deploy Maven Central

Swagger Core is a Java implementation of the OpenAPI Specification. Current version supports JAX-RS2 (javax and jakarta namespaces).

Get started with Swagger Core!

See the guide on getting started with Swagger Core to get started with adding Swagger to your API.

See the Wiki!

The github wiki contains documentation, samples, contributions, etc. Start there.

Compatibility

The OpenAPI Specification has undergone several revisions since initial creation in 2010. The Swagger Core project has the following compatibilities with the OpenAPI Specification:

Swagger core VersionRelease DateOpenAPI Spec compatibilityNotesStatus
2.2.23 (current stable)2024-08-283.xtag v2.2.23Supported
2.2.222024-05-153.xtag v2.2.22Supported
2.2.212024-03-203.xtag v2.2.21Supported
2.2.202023-12-193.xtag v2.2.20Supported
2.2.192023-11-103.xtag v2.2.19Supported
2.2.182023-10-253.xtag v2.2.18Supported
2.2.172023-10-123.xtag v2.2.17Supported
2.2.162023-09-183.xtag v2.2.16Supported
2.2.152023-07-083.xtag v2.2.15Supported
2.2.142023-06-263.xtag v2.2.14Supported
2.2.132023-06-243.xtag v2.2.13Supported
2.2.122023-06-133.xtag v2.2.12Supported
2.2.112023-06-013.xtag v2.2.11Supported
2.2.102023-05-153.xtag v2.2.10Supported
2.2.92023-03-203.xtag v2.2.9Supported
2.2.82023-01-063.xtag v2.2.8Supported
2.2.72022-11-153.0tag v2.2.7Supported
2.2.62022-11-023.0tag v2.2.6Supported
2.2.52022-11-023.0tag v2.2.5Supported
2.2.42022-10-163.0tag v2.2.4Supported
2.2.32022-09-273.0tag v2.2.3Supported
2.2.22022-07-203.0tag v2.2.2Supported
2.2.12022-06-153.0tag v2.2.1Supported
2.2.02022-04-043.0tag v2.2.0Supported
2.1.132022-02-073.0tag v2.1.13Supported
2.1.122021-12-233.0tag v2.1.12Supported
2.1.112021-09-293.0tag v2.1.11Supported
2.1.102021-06-283.0tag v2.1.10Supported
2.1.92021-04-203.0tag v2.1.9Supported
2.1.82021-04-183.0tag v2.1.8Supported
2.1.72021-02-183.0tag v2.1.7Supported
2.1.62020-12-043.0tag v2.1.6Supported
2.1.52020-10-013.0tag v2.1.5Supported
2.1.42020-07-243.0tag v2.1.4Supported
2.1.32020-06-273.0tag v2.1.3Supported
2.1.22020-04-013.0tag v2.1.2Supported
2.1.12020-01-023.0tag v2.1.1Supported
2.1.02019-11-163.0tag v2.1.0Supported
2.0.102019-10-113.0tag v2.0.10Supported
2.0.92019-08-223.0tag v2.0.9Supported
2.0.82019-04-243.0tag v2.0.8Supported
2.0.72019-02-183.0tag v2.0.7Supported
2.0.62018-11-273.0tag v2.0.6Supported
2.0.52018-09-193.0tag v2.0.5Supported
2.0.42018-09-053.0tag v2.0.4Supported
2.0.32018-08-093.0tag v2.0.3Supported
1.6.14 (current stable)2024-03-192.0tag v1.6.14Supported
1.6.132024-01-262.0tag v1.6.13Supported
1.6.122023-10-142.0tag v1.6.12Supported
1.6.112023-05-152.0tag v1.6.11Supported
1.6.102023-03-212.0tag v1.6.10Supported
1.6.92022-11-152.0tag v1.6.9Supported
1.6.82022-10-162.0tag v1.6.8Supported
1.6.72022-09-272.0tag v1.6.7Supported
1.6.62022-04-042.0tag v1.6.6Supported
1.6.52022-02-072.0tag v1.6.5Supported
1.6.42021-12-232.0tag v1.6.4Supported
1.6.32021-09-292.0tag v1.6.3Supported
1.6.22020-07-012.0tag v1.6.2Supported
1.6.12020-04-012.0tag v1.6.1Supported
1.6.02019-11-162.0tag v1.6.0Supported
1.5.242019-10-112.0tag v1.5.24Supported
1.5.232019-08-222.0tag v1.5.23Supported
1.5.222019-02-182.0tag v1.5.22Supported
1.5.212018-08-092.0tag v1.5.21Supported
1.5.202018-05-232.0tag v1.5.20Supported
2.0.22018-05-233.0tag v2.0.2Supported
2.0.12018-04-163.0tag v2.0.1Supported
1.5.192018-04-162.0tag v1.5.19Supported
2.0.02018-03-203.0tag v2.0.0Supported
2.0.0-rc42018-01-223.0tag v2.0.0-rc4Supported
2.0.0-rc32017-11-213.0tag v2.0.0-rc3Supported
2.0.0-rc22017-09-293.0tag v2.0.0-rc2Supported
2.0.0-rc12017-08-173.0tag v2.0.0-rc1Supported
1.5.182018-01-222.0tag v1.5.18Supported
1.5.172017-11-212.0tag v1.5.17Supported
1.5.162017-07-152.0tag v1.5.16Supported
1.3.122014-12-231.2tag v1.3.12Supported
1.2.42013-06-191.1tag swagger-project_2.10.0-1.2.4Deprecated
1.0.02011-10-161.0tag v1.0Deprecated

Change History

If you're interested in the change history of swagger and the Swagger Core framework, see here.

Prerequisites

You need the following installed and available in your $PATH:

  • Java 11
  • Apache maven 3.0.4 or greater
  • Jackson 2.4.5 or greater

To build from source (currently 2.2.24-SNAPSHOT)

# first time building locally
mvn -N

Subsequent builds:

mvn install

This will build the modules.

Of course if you don't want to build locally you can grab artifacts from maven central:

https://repo1.maven.org/maven2/io/swagger/core/

Sample Apps

The samples have moved to a new repository and contain various integrations and configurations.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing security@swagger.io, instead of using the public issue tracker.