java 如何生成接口文档

原创

mob64ca12dcc794 2024-04-17 05:57:14 ©著作权

文章标签 接口文档 spring UI 文章分类 Java 后端开发

©著作权归作者所有：来自51CTO博客作者mob64ca12dcc794的原创作品，请联系作者获取转载授权，否则将追究法律责任

使用Swagger生成接口文档

在Java开发中，生成接口文档是非常重要的一个环节。Swagger是一个流行的工具，可以帮助我们自动生成接口文档，并提供一个友好的UI界面供查看。

步骤

步骤一：引入Swagger依赖

首先，在项目的pom.xml文件中引入Swagger的依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

步骤二：配置Swagger

在Spring Boot的启动类中添加Swagger的配置信息：

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("这是一个示例API文档")
                .version("1.0")
                .build();
    }
}

步骤三：编写Controller

在Controller中添加一些接口示例：

@RestController
@RequestMapping("/api")
public class ExampleController {
    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/user/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

步骤四：访问Swagger UI

启动应用程序后，访问http://localhost:8080/swagger-ui.html即可查看生成的接口文档。

示例

pie
    title 接口文档统计
    "GET" : 30
    "POST" : 20
    "PUT" : 15
    "DELETE" : 10
    "PATCH" : 5

erDiagram
    CUSTOMER ||--o{ ORDER : has
    ORDER ||--|{ ORDERDETAIL : contains
    CUSTOMER {
        int id
        string name
        date birth
    }
    ORDER {
        int id
        int customer_id
        date order_date
    }
    ORDERDETAIL {
        int id
        int order_id
        int product_id
        int quantity
    }