使用Swagger在SpringBoot项目中管理API文档（使用Oauth2）

1 、修改pom.xml引入swagger

     

        
            io.springfox
            springfox-swagger-ui
            2.5.0
        
        
            io.springfox
            springfox-swagger2
            2.5.0
        
        

2、SwaggerConfig.java

import static com.google.common.collect.Lists.newArrayList;
import static springfox.documentation.builders.PathSelectors.ant;
import java.util.List;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.OAuthBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationCodeGrant;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.GrantType;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.service.TokenEndpoint;
import springfox.documentation.service.TokenRequestEndpoint;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.ApiKeyVehicle;
import springfox.documentation.swagger.web.SecurityConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * SwaggerConfig
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value("${security.userOauth.clientId}")
private String authClientId;

@Value("${security.userOauth.clientSecret}")
private String authClientSecret;

@Value("${security.userOauth.type}")
private String type;

@Value("${security.userOauth.authorizationUrl}")
private String authorizationUrl;

@Value("${security.userOauth.tokenUrl}")
private String tokenUrl;

@Value("${security.userOauth.tokenName}")
private String tokenName;

@Value("${security.userOauth.scope.code}")
private String scopeCode;

@Value("${security.userOauth.scope.desc}")
private String scopeDesc;

@Value("${app.key}")
private String appKey;

@Value("${app.name}")
private String appName;

@Value("${app.desc}")
private String appDesc;

@Value("${app.version}")
private String appVersion;

@Value("${app.termsOfServiceUrl}")
private String termsOfServiceUrl;

@Value("${app.contact.name}")
private String contactName;

@Value("${app.contact.url}")
private String contactUrl;

@Value("${app.contact.email}")
private String contactEmail;

@Value("${app.license}")
private String license;

@Value("${app.licenseUrl}")
private String licenseUrl;

/**
* Api分组，可以定义多个组
*/
@Bean
public Docket jackApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("jack")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("net.jack.lt"))
.build()
.securitySchemes(newArrayList(oauth()))
.securityContexts(newArrayList(securityContext()))
.apiInfo(jyxApiInfo());
}

private ApiInfo jyxApiInfo() {
ApiInfo apiInfo = new ApiInfo(appName, appDesc, appVersion, termsOfServiceUrl, 
new Contact(contactName, contactUrl, contactEmail),
license, licenseUrl);


return apiInfo;
}

@Bean
SecurityScheme apiKey() {
       return new ApiKey(appName, appKey, "header");
}


@Bean
SecurityContext securityContext() {
AuthorizationScope[] scopes = new AuthorizationScope[]{new AuthorizationScope(scopeCode, scopeDesc)};

SecurityReference securityReference = SecurityReference
.builder()
.reference(type)
.scopes(scopes)
.build();


return SecurityContext
.builder()
.securityReferences(newArrayList(securityReference))
.forPaths(ant("/api/**"))
.build();
}

@Bean
SecurityScheme oauth() {
return new OAuthBuilder()
.name(type)
.grantTypes(grantTypes())
.scopes(scopes())
.build();
}

List scopes() {
return newArrayList(new AuthorizationScope(scopeCode, scopeDesc));
}

List grantTypes() {
List grants = newArrayList(new AuthorizationCodeGrant(
new TokenRequestEndpoint(authorizationUrl, authClientId, authClientSecret),
new TokenEndpoint(tokenUrl, tokenName)));
return grants;
}

@Bean
public SecurityConfiguration securityInfo() {
return new SecurityConfiguration(authClientId, authClientSecret, scopeCode, 
appKey, appKey, ApiKeyVehicle.HEADER, "", ",");
}
}

3、在RESTful接口上添加注解@ApiOperation @ApiParam

     /**
 * 药品产品列表获取接口
 * pageNo 第几页
 * rows 每页条数
 * @return
 */
@RequestMapping(value = "/products", method = RequestMethod.GET)
@ApiOperation(value = "药品产品列表获取接口", notes = "可指定页码及每页条数")
@ResponseBody
public DrugProducts getDrugProductList(
@ApiParam(value="第几页") @RequestParam(required=false) Integer pageNo, 
@ApiParam(value="每页条数") @RequestParam(required=false) Integer rows) {

     }

或者

     @RequestMapping(value = "/hello", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value="问好", notes="向你问好")
@ApiImplicitParams({
        @ApiImplicitParam(name = "page", value = "第几页", required = false,
                dataType = "int", paramType = "query", defaultValue = "0"),
        @ApiImplicitParam(name = "count", value = "每页行数", required = false,
                dataType = "int", paramType = "query", defaultValue = "30"),
        @ApiImplicitParam(name = "name", value = "姓名", required = false,
                dataType = "string", paramType = "query", defaultValue = "")
})
public CommonParam hello(HttpServletRequest request) {

CommonParam commonParam = new CommonParam();
commonParam.setId(1);
commonParam.setName(request.getParameter("name"));
return commonParam;
}

4、在 application.properties或application.yml中增加配置项

security.userOauth.clientId=swagger-ui
security.userOauth.clientSecret=Sa0rk3kgx
security.userOauth.type=oauth2
security.userOauth.authorizationUrl=http://dev.jyx365.top/sso/login
security.userOauth.tokenUrl=http://dev.jyx365.top/oauth/access_token
security.userOauth.tokenName=access_token
security.userOauth.scope.code=userinfo
security.userOauth.scope.desc=用户信息
app.key=learning
app.name=每日一学
app.desc=每日一学RESTful
app.version=0.1
app.termsOfServiceUrl=http://blog.csdn.net/jacktonny1
app.contact.name=闫不由衷
app.contact.url=http://blog.csdn.net/jacktonny1
[email protected]
app.license=The Apache License, Version 2.0
app.licenseUrl=http://www.apache.org/licenses/LICENSE-2.0.html

或 application.yml
security:
  userOauth:
    clientId: swagger-ui
    clientSecret: Sa0rk3kgx
    type: oauth2
    authorizationUrl: http://dev.jyx365.top/sso/login
    tokenUrl: http://dev.jyx365.top/oauth/access_token
    tokenName: access_token
    scope:
      code: userinfo
      desc: 用户信息
app:
  key: learning
  name: 每日一学
  desc: 每日一学RESTful
  version: 0.1
  termsOfServiceUrl: http://blog.csdn.net/jacktonny1
  contact:
    name: 闫不由衷
    url: http://blog.csdn.net/jacktonny1
    email: [email protected]
  license: The Apache License, Version 2.0
  licenseUrl: http://www.apache.org/licenses/LICENSE-2.0.html

5、http://localhost:端口号/swagger-ui.html