首页天道酬勤,

,

张世龙 05-05 21:14 107次浏览

一、什么是swagger? 1、是一个可以更好地编写API文档规格且完整的框架。

2、提供说明、生产、消费和可视化rest风格的web服务。

3、是由巨大道具集合支撑的形式化规范。 该集合涵盖了从最终用户界面、底层代码库到业务API管理的各个方面。

nrdxlz :第三方依赖(最简单的方法) 1、在pom.xml文件中添加第三方依赖swagger )

ependencygroupidcom.spring 4all/groupidartifactidswagger-spring-boot-starter/artifactidversion1.7.0. release

3,3359 github.com/spring for all/spring-boot-starter-swagger这是github上这个swagger依赖实现的项目,里面有详细的解说。

温柔鸽:使用官方依赖1,在pom.xml文件中输入swagger相关依赖dependencygroupidio.spring fox/groupidartifactidspringfox-swagger2/artifactidversion ependencydependencygroupidio.spring fox/groupidartifactidspringfox-swagger-ui/artifactidversion 2.7

2、swagger configuration中最需要注意的是swagger scan base package,这是扫描注释的放置,也就是你的API界面的位置。

importorg.spring帧work.context.annotation.bean; importorg.spring framework.context.annotation.configuration; importspringfox.documentation.builders.apiinfobuilder; importspringfox.documentation.builders.path selectors; importspringfox.documentation.builders.requesthandlerselectors; importspringfox.documentation.service.API info; importspringfox.documentation.SPI.documentation type; importspringfox.documentation.spring.web.plugins.docket; importspringfox.documentation.swagger2. annotations.enable swagger 2; @ configuration @ enable swagger2public class swagger2{ @ beanpublicdocketcreaterestapi ((return new docket ) documentationtion typppppp . APIinfo(APIinfo ) ).select ).APIS ) requesthandlerselectors.base package ) ' com.yss.ms.admin ' ).Paths } private ApiInfo apiInfo () ({ return new ApiInfoBuilder ).title )服务:提供daocke镜像、权限管理、用户管理、页面管理、日志后台APIs

务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台") .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin") .contact("程序猿") .version("1.0") .build(); } } 三、具体使用 1、在API上做一些声明 //本controller的功能描述@Api(value = "pet", description = "the pet API")public interface PetApi { //option的value的内容是这个method的描述,notes是详细描述,response是最终返回的json model。其他可以忽略 @ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = { @Authorization(value = "petstore_auth", scopes = { @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"), @AuthorizationScope(scope = "read:pets", description = "read your pets") }) }, tags={ "pet", }) //这里是显示你可能返回的http状态,以及原因。比如404 not found, 303 see other @ApiResponses(value = { @ApiResponse(code = 405, message = "Invalid input", response = Void.class) }) @RequestMapping(value = "/pet", produces = { "application/xml", "application/json" }, consumes = { "application/json", "application/xml" }, method = RequestMethod.POST) ResponseEntity<Void> addPet( //这里是针对每个参数的描述 @ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body); 2、设定访问API doc的路由

在配置文件中,application.yml中声明:

springfox.documentation.swagger.v2.path: /api-docs

这个path就是json的访问request mapping.可以自定义,防止与自身代码冲突。

API doc的显示路由是:http://localhost:8080/swagger-ui.html

如果项目是一个webservice,通常设定home / 指向这里:

@Controllerpublic class HomeController { @RequestMapping(value = "/swagger") public String index() { System.out.println("swagger-ui.html"); return "redirect:swagger-ui.html"; }} 四:swagger的常用API 1、api标记

Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:

@Api(value = "/user", description = "Operations about user")

2、ApiOperation标记

ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

@ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"})

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-V8AEIZ2l-1609508640724)(http://ozpb6wow8.bkt.clouddn.com/22.png)]

3、ApiParam标记

ApiParam请求属性,使用方式:

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-5veQGqo7-1609508640725)(http://ozpb6wow8.bkt.clouddn.com/3.png)]

4、ApiResponse

ApiResponse:响应配置,使用方式:
@ApiResponse(code = 400, message = "Invalid user supplied")
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6nd1sH5D-1609508640729)(http://ozpb6wow8.bkt.clouddn.com/44.png)]

5、ApiResponses

ApiResponses:响应集配置,使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-SNlJ6vSI-1609508640730)(http://ozpb6wow8.bkt.clouddn.com/5.png)]

6、ResponseHeader

响应头设置,使用方法
@ResponseHeader(name="head1",description="response head conf")
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-NDXgB4JA-1609508640731)(http://ozpb6wow8.bkt.clouddn.com/6.png)]

,