25.JavaWeb-接口文档Swagger

1.Swagger

        swagger是一款可以根据resutful风格生成的生成的接口开发文档,并且支持做测试的一款中间软件。

1.1 接口文档

        接口文档是用于描述API的一份文档,它包含了API的详细信息,包括API的请求和响应参数、接口路径、请求方法、数据类型、返回数据结构等。

2.swagger常用注解

@RestController
@Api(tags = "图书管理API", description = "用于管理图书馆中图书的API")
public class BookController {
    @ApiOperation(value = "根据ID获取图书", notes = "根据图书ID从图书馆中获取图书")
    @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/books/{id}")
    public ResponseEntity getBookById(@PathVariable Long id) {
        // 省略业务逻辑
    }
    @ApiOperation(value = "更新图书", notes = "更新图书馆中现有的图书")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "book", value = "图书对象", required = true, dataType = "Book", paramType = "body")
    })
    @PutMapping("/books/{id}")
    public ResponseEntity updateBook(@PathVariable Long id, @RequestBody Book book){
        // 省略业务逻辑
    }
}
注解 位置 说明
@Api 类上 用于描述该类是"图书管理API",说明整个API的主要作用。
@ApiOperation 方法上 用于给API方法增加说明,描述每个方法的作用。例如,getBookById方法用于根据ID获取图书,addBook方法用于添加新图书。
@ApiImplicitParam 方法入参 用于给方法的入参增加说明,描述参数的作用和数据类型。在getBookById和deleteBook方法中,都有一个参数id,通过该注解说明id的作用和数据类型。
@ApiImplicitParams 方法上 用于包含一组参数说明,可以在一个注解中同时描述多个参数。在updateBook方法中,使用该注解描述两个参数:id表示图书ID,book表示图书对象。
@Data
@ApiModel(value = "封装商品信息对象")
public class Goods implements Serializable {
    @ApiModelProperty(value = "商品id",dataType = "int")
    private Integer id;
}
@ApiModel 用在返回对象类上,描述一个Model的信息。在本例中,Book类可能是一个POJO类,用于描述图书的信息。
@ApiModelProperty 用于描述一个model的属性。在本例中,如果Book类有其他属性,可以使用该注解为这些属性增加说明。例如,书名、作者、出版日期等。

3.使用Swagger

        使用swagger时,只需要在需要生成接口文档的handler中使用相关注解,swagger就可以自动生成接口文档

3.1 导入swagger依赖



    io.springfox
    springfox-swagger2
    2.9.2



    io.springfox
    springfox-swagger-ui
    2.9.2

3.2 编写swagger配置类

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("商品模块API文档")
                .description("采用restful风格接口")
                .version("1.0")
                .build();
    }
    @Bean
    public Docket docket(ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage(
                        "com.mall.mall100.controller"))
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

4.访问swagger接口文档

http://localhost:9090/swagger-ui.htmlicon-default.png?t=N6B9http://localhost:8080/swagger-ui.html

25.JavaWeb-接口文档Swagger_第1张图片

你可能感兴趣的:(JavaEE,java,开发语言)