在项目中使用Swagger文档

转载自:在项目中使用Swagger文档

1.为什么要使用Swagger?

前后端协作开发过程中,时间周期一长,接口文档就变得难以维护,而我们通过swagger 只需要平常在写代码的时候加上一些注解,就可以生成一个接口在线文档,进行一些简单的功能测试!

2.如何使用Swagger?
1).需要在pom.xml中引用jar包

<!-- swagger start -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<!-- swagger end -->

2)配置swagger文档的配置类

package com.test;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
/**
 * 功能描述: swagger文档的配置类
 * @Author: tanghh18
 * @Date: 2019/9/27 13:51
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage
                        ("com.test.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("前端 API")
                //创建人
                .contact(new Contact("soup_tang", "http://localhost:8084/", "XXXxxXX@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("加油!")
                .build();
    }
}

3.  Swagger常用的注解


@Api()   主要是用来描述当前类的作用,description是在swagger文档页面展示的备注信息
@ApiOperation()   value这个参数不在文档上面展示,notes是在文档上面展示的内容,httpMethod 是get 还是post请求

@ApiModelProperty 主要是用来描述当前这个参数的作用 

还有一些其他的注解:

(1)@ApiImplicitParams : 用在方法上包含多个参数说明。

(2)@ApiImplicitParam:用在方法上包含一个参数说明。

                                            paramType:指定参数放在哪个地方。
                                            name:参数名
                                            dataType:参数类型
                                            required:参数是否必须传
                                            value:说明参数
                                            defaultValue:参数的默认值

                                            header:请求参数放置于Request Header,使用@RequestHeader 获取。
                                            query:请求参数放置于请求地址,使用@RequestParam获取
                                            path:用于restful接口。
(3)@ApiResponses:用于表示一组响应。

(4)@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息。

                                      code:数字,例如400。
                                      message:信息,例如"请求参数没填好"。
                                      response:抛出异常的类   

4.如何在项目访问当前生成这个swagger文档? 

我此时项目的端口是8084 所以在页面上访问路径为:http://localhost:8084/swagger-ui.html

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
在 Go 1.17 ,你可以使用 embed 包将静态文件嵌入到可执行文件,因此可以将 Swagger UI 嵌入到 Go Web 项目,而不需要单独部署 Swagger UI。 以下是在 Goland 项目使用 Swagger 的步骤: 1. 安装 Swagger 相关依赖:在项目添加 `github.com/swaggo/swag` 和 `github.com/swaggo/gin-swagger` 两个依赖库,可以使用以下命令: ``` go get -u github.com/swaggo/swag go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/gin-swagger/swaggerFiles ``` 2. 在项目添加 Swagger 注释:在需要生成 Swagger 文档的接口上添加注释,例如: ``` // @Summary 获取用户信息 // @Description 根据用户ID获取用户信息 // @Tags 用户管理 // @Produce json // @Param id path int true "用户ID" // @Success 200 {object} UserResponse // @Failure 400 {string} string "请求参数错误" // @Router /users/{id} [get] func GetUserByID(c *gin.Context) { // ... } ``` 3. 生成 Swagger 文档:在项目根目录下执行以下命令,生成 Swagger 文档: ``` swag init ``` 该命令会在项目生成一个 `docs` 目录,其包含了 Swagger 文档的 JSON 文件和 HTML 文件。 4. 在项目嵌入 Swagger UI:在项目添加一个 `swagger` 目录,并将 Swagger UI 的静态文件拷贝到该目录。可以从 Swagger 官网(https://swagger.io/tools/swagger-ui/)下载最新的 Swagger UI 版本。 ``` ├── main.go ├── go.mod ├── go.sum ├── docs │ ├── docs.go │ ├── swagger.json │ └── swagger.yaml └── swagger ├── index.html ├── swagger-ui-standalone-preset.js ├── swagger-ui-standalone-preset.js.map ├── swagger-ui.css ├── swagger-ui.css.map ├── swagger-ui.js ├── swagger-ui.js.map └── swagger-ui.min.js ``` 5. 在项目添加 Swagger UI 的路由:在项目添加一个路由,将 Swagger UI 的 HTML 文件和静态文件提供给用户访问,例如: ``` router.GET("/swagger/*any", gin.WrapH(http.FileServer(http.Dir("./swagger")))) ``` 这样,用户可以通过访问 `/swagger/index.html` 来查看 Swagger 文档。 6. 启动项目并访问 Swagger UI:在 Goland 启动项目,然后在浏览器访问 `http://localhost:8080/swagger/index.html`,即可访问 Swagger UI 并查看文档。 需要注意的是,这种方式虽然可以将 Swagger UI 嵌入到可执行文件,但是每次修改 Swagger UI 后都需要重新编译可执行文件,因此不建议在生产环境使用。如果你需要在生产环境使用 Swagger UI,建议单独部署一个 Swagger UI 服务。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值