SpringBoot使用Swagger创建在线接口文档

一、介绍


可以访问一下这个

Spring Boot整合swagger使用教程 - 随风行云 - 博客园 (cnblogs.com)

 

    Swagger 是为了方便用户在创建一个接口时,自动创建一个接口文档。

    优点:

自动生成文档,只需要在接口中使用注解进行标注(@ApiModel  @ApiParam)

自动更新文档,当接口被修改,文档也会自动对应修改

支持在线进行调试。

    缺点:

不能创建测试用例,如果需要对测试用例,可以使用postman。

规范问题

没有接口文档的更新管理,一个接口更新之后,可能不关心旧版的接口信息。


二、步骤:

    2.1  在maven中添加依赖:

<!--        swagger-->

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

 

 

    2.2 进行swagger的配置

package com.qiang.config;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**

* @author 
* @ClassName SwaggerConfig
* @description: 在线配置文档类
* @dtetime 2023年 06月 27日 15:55
* @version: 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).
                pathMapping("/").select().
                apis(RequestHandlerSelectors.basePackage("com.qiang")).
                paths(PathSelectors.any()).
                build().apiInfo(new ApiInfoBuilder().title("SpringBoot整合Swagger").
                description("上班拿去用吧").
               version("1.0").
                contact(new Contact("qiang","http://www.qiang.com","forhappiness19@163.com"))
               .license("The Apache license").
                        licenseUrl("http://www.qiang.com").build());  }
}

 

 

    2.3 进行控制器(模拟接口)的配置

@RestController
@Api(tags = "这是一个swagger的一个简单的项目组")
public class SwaggerController {
 
    @GetMapping("/get")
    @ApiOperation(value = "第一个测试" ,notes = "第一个测试的note")
    public String get(){
        return "aaa";
    }

    @GetMapping("/list")
    @ApiOperation(value = "第二个测试" ,notes = "第二个测试的note")
    public String list(String id){
        return "第二个测试 "+id;
    }
}

      2.4访问http://localhost:端口号/swagger-ui.html


 三。常用注解:

@Api: 用于类,标识这个类是swagger的资源

@ApiIgnore: 用于类,忽略该 Controller,指不对当前类做扫描

@ApiOperation: 用于方法,描述 Controller类中的 method接口

@ApiParam: 用于参数,单个参数描述,与 @ApiImplicitParam不同的是,他是写在参数左侧的。如( @ApiParam(name="username",value="用户名")Stringusername)

@ApiModel: 用于类,表示对类进行说明,用于参数用实体类接收

@ApiProperty:用于方法,字段,表示对model属性的说明或者数据操作更改

@ApiImplicitParam: 用于方法,表示单独的请求参数

@ApiImplicitParams: 用于方法,包含多个 @ApiImplicitParam

@ApiResponse: 用于方法,描述单个出参信息

@ApiResponses: 用于方法,包含多个@ApiResponse

@ApiError: 用于方法,接口错误所返回的信息

posted @ 2023-09-10 16:14  forshine123  阅读(56)  评论(0编辑  收藏  举报