在Debian上自动生成Swagger文档,通常涉及以下几个步骤:
安装必要的工具:
在Debian上安装这些工具的命令如下:
sudo apt update
sudo apt install openjdk-11-jdk
sudo apt install maven
sudo apt install gradle
下载并安装Swagger Codegen CLI:
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.29/swagger-codegen-cli-3.0.29.jar -O swagger-codegen-cli.jar
编写API规范:
使用OpenAPI Specification(OAS)编写API规范文件,通常是swagger.yaml
或swagger.json
。例如,创建一个swagger.yaml
文件:
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: List all users
responses:
'200':
description: An array of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
生成文档: 使用Swagger Codegen CLI工具生成API文档。例如,生成HTML格式的API文档:
java -jar swagger-codegen-cli.jar generate \
-i path/to/swagger.yaml \
-l html2 \
-o path/to/output/directory
集成到构建过程: 将Swagger Codegen集成到Maven或Gradle的构建过程中,以便在每次构建时自动生成代码和文档。
Maven示例:
在pom.xml
中添加Swagger Codegen插件:
<build>
<plugins>
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>5.2.1</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
<generatorName>java</generatorName>
<output>${project.build.directory}/generated-sources</output>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
Gradle示例:
在build.gradle
中添加Swagger Codegen任务:
plugins {
id 'org.openapitools.codegen' version '5.2.1'
}
openApiGenerate {
inputSpec = file("${projectDir}/src/main/resources/swagger.yaml").toString()
generatorName = 'java'
outputDir = file("${buildDir}/generated-sources")
}
访问Swagger页面:
Spring Boot应用运行后,通过访问http://localhost:端口号/swagger-ui.html
,即可查看自动生成的接口文档。
如果使用Springfox和Knife4j,可以参考以下配置:
在pom.xml
中添加Springfox和Knife4j依赖:
<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>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>3.0.3</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
创建Swagger配置类:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API 文档标题")
.contact(new Contact("联系人姓名", "联系人网址", "联系人邮箱"))
.version("版本号")
.build();
}
}
在SwaggerProvider.java
类中添加@Primary
注解:
@Primary
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
}
通过以上步骤,你可以在Debian上实现Swagger文档的自动生成,并根据具体需求选择生成不同语言的客户端代码或不同格式的API文档。