文档

引入 1 2 3 4 go install github.com/swaggo/swag/cmd/swag@latest go get -u -v github.com/swaggo/gin-swagger go get -u -v github.com/swaggo/files go get -u -v github.com/alecthomas/template 使用 基础注释 main函数中配置项目基本注解 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 package main // @title 这里写标题 // @version 1.0 // @description 这里写描述信息 // @termsOfService http://swagger.io/terms/ // @contact.name 这里写联系人信息 // @contact.url http://www.swagger.io/support // @contact.email support@swagger.io // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host 这里写接口服务的host // @BasePath 这里写base path // @securityDefinitions.basic BasicAuth func main() { r := gin.New() r.Run() } api注解 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 // 函数名 ShowAccount godoc // @Summary Show an account // @Description get string by ID // @Tags accounts // @Accept json // @Produce json // @Param id path int true "Account ID" // @Success 200 {object} model.Account // @Failure 400 {object} httputil.HTTPError // @Failure 404 {object} httputil.HTTPError // @Failure 500 {object} httputil.HTTPError // @Router /accounts/{id} [get] func GetPostListHandler2(c *gin.Context) { ... } 生成docs文件 1 swag init 配置文档handler 1 engine := gin.New()engine.GET("swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) 测试 1 ip:port/swagger/index.html

依赖 1 2 3 4 5 6 <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.1.0</version> </dependency> 配置 1 2 3 4 5 6 springdoc: api-docs: path: /api-docs swagger-ui: path: /swagger-ui.html show-actuator: true 使用 注解 注解 标注位置 作用 @Tag controller 类 标识 controller 作用 @Parameter 参数 标识参数作用 @Parameters 参数 参数多重说明 @Schema model 层的 JavaBean 描述模型作用及每个属性 @Operation 方法 描述方法作用 @ApiResponse 方法 描述响应状态码等 docket配置 单个docket 1 2 3 springdoc: packagesToScan:package1,package2 pathsToMatch:/v1,/api/balance/** 多个docket 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("springshop-public") .pathsToMatch("/public/**") .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("springshop-admin") .pathsToMatch("/admin/**") .addMethodFilter(method -> method.isAnnotationPresent(Admin.class)) .build(); } OpenApi配置 1 2 3 4 5 6 7 8 9 10 11 @Bean public OpenAPI springShopOpenAPI() { return new OpenAPI() .info(new Info().title("SpringShop API") .description("Spring shop sample application") .version("v0.0.1") .license(new License().name("Apache 2.0").url("http://springdoc.org"))) .externalDocs(new ExternalDocumentation() .description("SpringShop Wiki Documentation") .url("https://springshop.wiki.github.org/docs")); }