江苏龙网

  1. 主页 > 生活百科 > >

SpringBoot接口 - 如何生成接口文档之Swagger技术栈？( 二 )

Swagger

controller接口package tech.pdai.springboot.swagger.controller;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.*;import tech.pdai.springboot.swagger.entity.param.UserParam;import tech.pdai.springboot.swagger.entity.vo.AddressVo;import tech.pdai.springboot.swagger.entity.vo.UserVo;import java.util.Collections;import java.util.List;/** * @author pdai */@Api@RestController@RequestMapping("/user")public class UserController {/*** http://localhost:8080/user/add .** @param userParam user param* @return user*/@ApiOperation("Add User")@PostMapping("add")@ApiImplicitParam(name = "userParam", type = "body", dataTypeClass = UserParam.class, required = true)public ResponseEntity<String> add(@RequestBody UserParam userParam) {return ResponseEntity.ok("success");}/*** http://localhost:8080/user/list .** @return user list*/@ApiOperation("Query User List")@GetMapping("list")public ResponseEntity<List<UserVo>> list() {List<UserVo> userVoList = Collections.singletonList(UserVo.builder().name("dai").age(18).address(AddressVo.builder().city("SZ").zipcode("10001").build()).build());return ResponseEntity.ok(userVoList);}}运行测试打开文档API网页

SpringBoot接口 - 如何生成接口文档之Swagger技术栈？

文章插图
 
测试添加一个用户
SpringBoot接口 - 如何生成接口文档之Swagger技术栈？

文章插图
 
查询用户列表
SpringBoot接口 - 如何生成接口文档之Swagger技术栈？

文章插图
 
实现案例之Knife4J
这里展示目前使用Java生成接口文档的最佳实现: SwaggerV3(OpenAPI）+ Knife4J 。
POM<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version></dependency>yml配置server:port: 8080knife4j:enable: truedocuments:- group: Test Groupname: My Documentslocations: classpath:wiki/*setting:# default langlanguage: en-US# footerenableFooter: falseenableFooterCustom: truefooterCustomContent: MIT | [Java 全栈](https://pdai.tech)# headerenableHomeCustom: truehomeCustomLocation: classpath:wiki/README.md# modelsenableSwaggerModels: trueswaggerModelName: My Models注入配置package tech.pdai.springboot.knife4j.config;import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.http.HttpMethod;import springfox.documentation.builders.*;import springfox.documentation.oas.annotations.EnableOpenApi;import springfox.documentation.schema.ScalarType;import springfox.documentation.service.*;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import tech.pdai.springboot.knife4j.constant.ResponseStatus;import java.util.ArrayList;import java.util.List;import java.util.stream.Collectors;/** * swagger config for open api. * * @author pdai */@Configuration@EnableOpenApipublic class OpenApiConfig {/*** open api extension by knife4j.*/private final OpenApiExtensionResolver openApiExtensionResolver;@Autowiredpublic OpenApiConfig(OpenApiExtensionResolver openApiExtensionResolver) {this.openApiExtensionResolver = openApiExtensionResolver;}/*** @return swagger config*/@Beanpublic Docket openApi() {String groupName = "Test Group";return new Docket(DocumentationType.OAS_30).groupName(groupName).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build().globalRequestParameters(getGlobalRequestParameters()).globalResponses(HttpMethod.GET, getGlobalResponse()).extensions(openApiExtensionResolver.buildExtensions(groupName)).extensions(openApiExtensionResolver.buildSettingExtensions());}/*** @return global response code->description*/private List<Response> getGlobalResponse() {return ResponseStatus.HTTP_STATUS_ALL.stream().map(a -> new ResponseBuilder().code(a.getResponseCode()).description(a.getDescription()).build()).collect(Collectors.toList());}/*** @return global request parameters*/private List<RequestParameter> getGlobalRequestParameters() {List<RequestParameter> parameters = new ArrayList<>();parameters.add(new RequestParameterBuilder().name("AppKey").description("App Key").required(false).in(ParameterType.QUERY).query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))).required(false).build());return parameters;}/*** @return api info*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("My API").description("test api").contact(new Contact("pdai", "http://pdai.tech", "suzhou.daipeng@gmail.com")).termsOfServiceUrl("http://xxxxxx.com/").version("1.0").build();}}


推荐阅读


上一篇：.Net WebApi 实现 接口版本控制并打通Swagger支持

下一篇：linux系统下怎么修改文件所属用户和组？