使用Swagger2生成API文档

2019-05-28 08:49:37 阅读：598 来源： 互联网

标签：Swagger2 ApiOperation API 文档 swagger id

Swagger2是一个开源软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用Restful Web服务。

这是“维基百科”上对于Swagger2的一个介绍，可见Swagger2是属于第三方框架，对标的是Restful风格的API，使用Swagger2生成API文档，避免了传统手工记录的繁琐，也便于保存、整理、查阅和调试API接口。
#####在SpringBoot项目中引入Swagger2：

pom.xml引入对应的依赖

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

增加SwaggerConfig.java配置文件，在Applcation.java中添加@EnableSwagger2，项目启动时同时加载swagger2

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //接口对应包下的类，生成API文档
            .apis(RequestHandlerSelectors.basePackage("io.swagger.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("可读小说")
            .description("后台管理系统API文档")
            .termsOfServiceUrl("https://swagger.io/")
            .version("1.0.1")
            .build();
    }
}

同时利用Swagger2提供的注解对接口进行说明，通过访问http://localhost:8080/swagger-ui.html便可获取到相关API文档。
#####注解的使用（demo）

@Api(tags="小说信息接口")
@RestController
@RequestMapping("/info")
public class InfoController {

    @ApiOperation("添加小说信息")
    @PutMapping("/add")
    private String addInfo(){
        return "success";
    }

    @ApiOperation("获取小说信息")
    @GetMapping("/{id}")
    private String getInfo( @ApiParam("小说id") @PathVariable("id")int id){
        return "info" + id;
    }
}

运行结果

最后再说说Swagger2的常用注解：

@Api：用于类，表示标识这个类是swagger的资源
@ApiOperation：用于方法，表示一个http请求的操作
@ApiParam：用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）
@ApiModel：用于类，表示对数据模型进行说明，用于参数用实体类接收
@ApiModelProperty：用于方法，字段，表示对model属性的说明
@ApiIgnore：用于类，方法，方法参数，对应的将不会被显示到文档里
@ApiImplicitParam：用于方法，作用于非对象参数集
@ApiImplicitParams：用于方法，包含多个 @ApiImplicitParam

标签：Swagger2,ApiOperation,API,文档,swagger,id
来源： https://blog.csdn.net/hsf15768615284/article/details/90631996

本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享；
2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关；
3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关；
4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除；
5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。

ICode9

使用Swagger2生成API文档