Swagger示例 - 技术栈

对于项目完成后不用写文档,好处还是蛮大的

不需要关注项目其他只关注接口与实体类即可

SpringBoot项目

依赖

复制代码

<!--Swagger依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

启动类或者配置类添加开启Swagger注解

对于SpringBoot版本2.6以上的需要配置文件里加个配置不然启动报错(设置个路径)

复制代码

SpringBoot版本2.6以上,需要在配置文件里假如  解决SpringBoot2.6.2使用Swagger的问题

浏览器访问: http://ip:port/上下文/swagger-ui.html

可以写个Swagger配置类

@Configuration
public class SwaggerConfig {

    //配置Swagger docket的bean实例
    @Bean
    public Docket docket(){

        //1.创建Docket对象
        Docket docket=new Docket(DocumentationType.SWAGGER_2);

        //2.创建API信息,接口文档总体描述
        /**
         * 使用指定的信息构造 ApiInfo 的实例。
         *
         * @param title               API 的标题。
         * @param description         API 的描述。
         * @param version             API 的版本。
         * @param termsOfServiceUrl   API 的服务条款 URL。
         * @param contact             API 的联系信息。
         * @param license             API 的许可证信息。
         * @param licenseUrl          API 许可证的 URL。
         * @param vendorExtensions    要包含在 API 文档中的额外供应商扩展。
         */
        ApiInfo apiInfo=new ApiInfoBuilder()
                .title("图书馆管理系统 API")
                .version("1.0.0")
                .description("前后端分离项目,前端vue,后端SpringBoot+Dubbo分布式项目")
                .contact(new Contact("hrui", "www.hrui.com", "376084295@qq.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.opensource.org/licenses/mit-license.php")
                .build();
        //3.使用ApiInfo
        docket = docket.apiInfo(apiInfo);
        //4.设置参与文档生成的包
        docket=docket.select().apis(RequestHandlerSelectors.basePackage("com.example.controller")).build();
        return docket;

    }


}

下面介绍一款国人开发整合的叫knife4j

git地址

swagger-bootstrap-ui-demo: knife4j 以及swagger-bootstrap-ui 集成框架示例项目

用法不注释掉也可以两个可以一起使用

看下新的页面效果

访问http://ip:端口/上下文/doc.html

两个可以一起使用我这里没有配置上下文路径访问路径分别为

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

http://localhost:8080/doc.html

Swagger注解

@Api：用于描述整个Controller API的信息，包括API的标题、描述等。
@ApiOperation：用于描述单个接口，包括接口的HTTP方法、URL路径、接口的描述等。
@ApiParam和@ApiImplicitParam和@ApiImplicitParams：用于描述接口中的参数信息。

@ApiResponse：用于描述接口的响应信息，可以包括多个响应。
@ApiResponses ：用于包装多个@ApiResponse注解，可以用于一个接口有多个响应情况的情形。
@ApiModel：用于描述一个DTO（数据传输对象）类。
@ApiModelProperty：用于描述DTO类中的属性信息。
@ApiIgnore ：用于忽略某个类、方法或字段，不在Swagger文档中显示。@ApiIgnore

查看效果

后续都用这个国人改造的感觉好看点

paramType 是这些注解中一个重要的属性，表示参数的位置，常见取值有：

query： 参数在 URL 中，例如：http://example.com/resource?param1=value1&param2=value2。
path： 参数是 URL 的一部分，例如：/resource/{param}。
header： 参数在请求头中。
body： 复杂对象参数通常放在请求体中，适用于 POST 或 PUT 请求。
form： 参数以表单的形式提交，通常用于 POST 请求。