Java Swagger使用教程

下面是Java Swagger使用教程的完整攻略：

1. 什么是Swagger？

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger包含了许多强大的工具，可以使用它们来构建、文档化和测试RESTful API。

2. Swagger的优点

Swagger最大的好处是它使API文档变得容易，让API更容易被其他开发人员阅读和使用。以下是Swagger的一些优点：

• 自动生成API文档
• 通过UI测试API
• 标准化API开发
• 与多种编程语言和框架兼容
• 容易维护和扩展

3. Java Swagger使用教程

3.1 引入Swagger

在Maven项目中，只需要在pom.xml文件中添加以下依赖项即可：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

如果你正在使用Spring Boot，你还需要添加以下依赖项：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

3.2 配置Swagger

在Spring Boot项目中，只需要创建一个类并提供以下内容即可进行Swagger的配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

代码中各行的功能分别如下：

• @Configuration：标记这个类作为Spring的配置类
• @EnableSwagger2：启用Swagger
• @Bean：生成Bean实例
• Docket：Swagger的主要实体，它保存了API文档的基本信息
• DocumentationType.SWAGGER_2：指定了Swagger版本
• select()：返回一个API选择器，允许你指定生成API的策略
• apis()：指定一些需要生成API的Controller
• paths()：指定需要生成API的路径
• build()：生成Swagger配置

3.3 使用Swagger

配置完成后，只需要启动你的应用并访问以下地址来查看自动生成的Swagger文档：

http://localhost:8080/swagger-ui.html

上面的地址中，端口号需要改成你的应用实际的端口号。

Swagger页面的使用非常简单，你可以看到调用每个API时需要提供的参数以及预计的响应。

4. 示例：

下面提供两个示例，演示Swagger在Java中如何工作：

4.1 示例一：定义Controller

下面是一个简单的Spring Boot Controller：

@RestController
public class UserController {

    @GetMapping(value = "/users/{id}")
    public User getUserById(@PathVariable long id) {
        return new User(id, "John Doe");
    }

    static class User {
        public long id;
        public String name;

        public User(long id, String name) {
            this.id = id;
            this.name = name;
        }
    }
}

4.2 示例二：配置Swagger

通过以下配置使Swagger在应用中工作：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.regex("/users.*"))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "User API",
                "API for creating and managing user resources",
                "1.0",
                "Terms of service",
                new Contact("John Doe", "www.example.com", "[e-mail]"),
                "License of API", "API license URL", Collections.emptyList());
    }
}

4.3 示例三：测试API

启动应用并访问Swagger的页面，找到你定义的API并测试它：

GET http://localhost:8080/users/123

你应该会在返回中看到以下信息：

{ "id": 123, "name": "John Doe" }

以上便是Java Swagger使用教程的完整攻略。